MemoryAPI 开发者文档
目录

Vuepress 静态文档站点

学习目标

在这里，你将系统学习了解 Vuepress 静态文档站点的快速搭建技巧和相关配置详解

我们将以最简单直接的方式为您呈现内容！

# 🍗 Vuepress 文档站点 部署

# 快速搭建

  • 创建并更改为新目录
mkdir vuepress-starter && cd vuepress-starter
  • 使用首选包管理器初始化
yarn init
  • 在本地安装 VuePress
yarn add -D vuepress
  • 创建您的第一个文档
mkdir docs && echo '# Hello VuePress' > docs/README.md
  • 在 package.json 下添加如下配置
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
  • 效果如下：

image-20231127233627342

# 配置详解

# 侧边栏配置

  • 这里着重详解下 Vuepress 文档站点的侧边栏配置，官方文档在这方面的编写实在是有点含糊不清

官方文档：默认主题配置 | VuePress (vuejs.org) (opens new window)

  • 不同页面显示不同的侧边栏
  • 侧边栏分组
  • 分组可折叠？？？
  • 侧边栏展示标题深度
  • 两个全局配置：活动标题链接（默认开启）和展开所有标题链接（默认关闭）
  • 自动生成侧边栏：.js 配置方式 + .md 配置方式，后者更灵活，能配置标题
  • 禁用侧边栏

# 首页

module.exports = {
  theme: "vdoing", // 使用依赖包主题
  // theme: require.resolve('../../vdoing'), // 使用本地主题 (先将vdoing主题文件下载到本地：https://github.com/xugaoyi/vuepress-theme-vdoing)
  title: "Memory-API 开发者文档",
  description: "🚀为简化开发而生",
  base: "/memory-api-docs/",

  ..............................
}

# 主题配置

  // 主题配置
  themeConfig: {
    // 导航栏配置
    nav: [
      { text: "首页", link: "/" },
      {
        text: "操作指南",
        link: "/pages/52d5c3/",
        items: [
          { text: "概述", link: "/pages/52d5c3/" },
          { text: "系统设计", link: "/pages/a2f161/" },
          { text: "维护升级", link: "/pages/793dcb/" },
        ],
      },
      {
        text: "项目亮点",
        link: "/pages/8dfad9/",
        items: [
          { text: "内容概览", link: "/pages/8dfad9/" },
          {
            items: [
              { text: "Ant Design Pro", link: "/pages/c02666/" },
              { text: "Ant Design 组件库", link: "/pages/c0265f/" },
              { text: "OpenAPI 生成接口", link: "/pages/c0262g/" },
              { text: "Vuepress 文档站点", link: "/pages/c02622/" },
            ],
          },
        ],
      },
      {
        text: "问题答疑",
        link: "/pages/9cc27d/",
        items: [
          { text: "简介", link: "/pages/9cc27d/" },
          { text: "常见问题与解答", link: "/pages/9cc288/" },
        ],
      },
    ],
    // 侧边栏
    sidebarDepth: 2, // 侧边栏显示深度，默认1，最大2（显示到h3标题）

    ................................
    },

# 其他

  • 这里先回答之前的两个傻逼的问题：

    🤡 选中导航栏后，默认为第一个子文件，也就是说，导航栏下没有默认 README.md 页面

    • 这是什么意思呢？就是这个意思：

    image-20231206222316398

    • 这不就很简单？配置好导航栏菜单的跳转就可以了：
      nav: [
      { text: "首页", link: "/" },
      {
        text: "指南",
        link: "/pages/52d5c3/",
        items: [
          { text: "简介", link: "/pages/52d5c3/" },
          { text: "安装", link: "/pages/a2f161/" },
          { text: "快速开始", link: "/pages/793dcb/" },
          { text: "返回响应码", link: "/pages/2f674a/" },
          {
            text: "API接口",
            items: [
              { text: "随机壁纸", link: "/pages/8dfab5/" },
              { text: "随机名言", link: "/pages/dd027d/" },
              { text: "天气查询", link: "/pages/2b8e22/" },
              { text: "获取IP信息归属地", link: "/pages/0fc1d2/" },
            ],
          },
        ],
      },
     .......................
    ],

    🤡 显示文章的右侧目录

# Gitee 部署

  • 部署之前肯定要有 Gitee 远程仓库吧，创建一个新仓库，这里新仓库名就叫 VuepressDocs3了**（2023/11/28 晚）**

image-20231128173007530

  • 在 .vuepress/config.js下，作如下配置：
module.exports = {
  title: "Mem-API 开发者文档",
  description: "🚀为简化开发而生",
  base: "/vuepress-docs3/",
  head: [["link", { rel: "icon", href: `favicon.png` }]],
  themeConfig: {
    // 主题设置
    logo: "/favicon.png",
    nav: [ ...
    ],
    sidebar: { ...
    },
  },
};

  • 这里注意，base 的值对应的是将要部署的 Gitee 仓库地址，看清楚上面新仓库的地址：vuepress-docs3

  • 执行以下命令，打包：

yarn docs:build
  • 然后你就会神奇的发现，.vuepress 目录下多了一个 dist 文件夹，这就是打包好的静态网站文件了

image-20231128173335872

  • 把 dist 下的文件远程推送到指定 Gitee 远程仓库中，开启 GiteePages 服务：

image-20231128173500061

image-20231128173533059

# 踩坑记录

  • 踩过的坑算很多了，这里一并提一下：

2023/11/26 晚

了解到了 Vuepress 的 全局安装（不支持了）、局部安装 和 直接通过第三方主题安装，并了解了相关配置

总结来讲，这晚尝试了下 Vuepress 站点的简单配置，还没开始部署

  • 妈的，搞了一晚上 Vuepress ，好像没啥成果，但我总得记录一些东西吧：

    • 部署 Vuepress 文档站点：原生（全局安装、局部安装） / 第三方主题

    • 局部安装，好多东西还得自己配置，我哪来的闲心

    • 全局安装的话，他奶奶的，执行命令还不起作用

    • 第三方主题，感觉很不亲切

    • 尝试部署 Github，大体上成功了，但是打包完成后执有问题，现在本地部署也出现问题了

2023/11/27 晚

  • 也就睡前半个多小时，简单地搞了搞，发现在 Github 上可以直接拉官方代码，实现全局安装

🚀 下载地址：vuejs/vuepress at v1.9.10 (github.com) (opens new window)

image-20231127233627342

  • 还想着在这个基础上修修改改，做个文档站点，不过真的复杂，看看了解即可，在这个基础上做改动太不实际了，直接劝退
  • 那就用前天晚上的成果，直接着手部署了：Github / Gitee

🍻 推荐阅读：vuepress 打包部署到 Gitee Pages 访问页面出现样式丢失_De Ja Vu 幻觉记忆的博客-CSDN 博客 (opens new window)

  • Github 不想多说，太他妈吃网速了，访问慢不说，好不容易推送成功，还老是显示部署失败，发了十几条邮箱信息都没咋注意：

image-20231128175139846

image-20231128175234867

  • 呐，上面就是 Github Pages 服务了，太卡了，部署不了，不过网速好的话是没有问题的**（2023/11/28 晚）**

# 🦪 Vdoing 文档站点 部署

# 快速搭建

  • 拉取官方 demo**（2023/12/06 晚）**

官网地址：快速上手 | vuepress-theme-vdoing (xugaoyi.com) (opens new window)

  • 如下，直接按照官方文档的步骤，拉取官方文档站点预设 demo（这一步不用作过多详细解释了，看官方文档就行）：

image-20231206214916590

  • 拉取成功，简单看一下目录结构（官网提供），最重要的配置文件就是 docs/.vuepress/config.js 配置文件了：
.
├── .github   (可选，GitHub 相关文件)
│   ├── workflows
│   │   ├── baiduPush.yml (可选，百度定时自动推送)
│   │   └── ci.yml (可选，自动部署)
├── docs (必须，不要修改文件夹名称)
│   ├── .vuepress （同官方，查看：https://vuepress.vuejs.org/zh/guide/directory-structure.html#目录结构）
│   ├── @pages (可选，自动生成的文件夹，存放分类页、标签页、归档页)
│   ├── _posts (可选，专门存放碎片化博客文章的文件夹)
│   ├── <结构化目录>
│   └── index.md (首页)
├── vdoing (可选，本地的vdoing主题)
├── utils  (可选，vdoing主题使用的node工具)
│   ├── modules
│   ├── config.yml (可选，批量操作front matter配置)
│   ├── editFrontmatter.js (可选，批量操作front matter工具)
├── baiduPush.sh (可选，百度推送命令脚本)
├── deploy.sh (可选，部署命令脚本)
│
└── package.json

  • 简单修改配置：

  • 基本上所有配置官方都已经替我们做好了，我们要做的仅仅是改改 网站标题、导航栏、侧边栏，然后把博文替换成自己的就行

  • 简单甩出我的配置，仅供参考，详细的配置这里不作过多介绍，需要靠自己慢慢摸索

const baiduCode = require("./config/baiduCode.js"); // 百度统计hm码
module.exports = {
  theme: "vdoing", // 使用依赖包主题
  // theme: require.resolve('../../vdoing'), // 使用本地主题 (先将vdoing主题文件下载到本地：https://github.com/xugaoyi/vuepress-theme-vdoing)
  title: "Memory-API-接口开放平台",
  description: "🚀为简化开发而生",
  base: "/vdoing-doc/", // 默认'/'。如果你想将你的网站部署到如 https://foo.github.io/bar/，那么 base 应该被设置成 "/bar/",（否则页面将失去样式等文件）
  // 主题配置
  themeConfig: {
    nav: [
      { text: "首页", link: "/" },
      {
        text: "指南",
        link: "/pages/52d5c3/",
        items: [
          { text: "简介", link: "/pages/52d5c3/" },
          { text: "安装", link: "/pages/a2f161/" },
          { text: "快速开始", link: "/pages/793dcb/" },
          { text: "返回响应码", link: "/pages/2f674a/" },
          {
            text: "API接口",
            items: [
              { text: "随机壁纸", link: "/pages/8dfab5/" },
              { text: "随机名言", link: "/pages/dd027d/" },
              { text: "天气查询", link: "/pages/2b8e22/" },
              { text: "获取IP信息归属地", link: "/pages/0fc1d2/" },
            ],
          },
        ],
      },
      {
        text: "配置",
        link: "/pages/ce175c/",
        items: [{ text: "使用配置", link: "/pages/ce175c/" }],
      },
      { text: "案例", link: "/pages/5d571c/" },
      { text: "问答", link: "/pages/9cc27d/" },
      { text: "赞助", link: "/pages/1b12ed/" },
    ],
    sidebarDepth: 2, // 侧边栏显示深度，默认1，最大2（显示到h3标题）
    logo: "/img/logo.png", // 导航栏logo
    repo: "xugaoyi/vuepress-theme-vdoing", // 导航栏右侧生成Github链接
    searchMaxSuggestions: 10, // 搜索结果显示最大数
    lastUpdated: "上次更新", // 更新的时间，及前缀文字   string | boolean (取值为git提交时间)

    // 以下配置是Vdoing主题改动的和新增的配置
    sidebar: { mode: "structuring", collapsable: false }, // 侧边栏  'structuring' | { mode: 'structuring', collapsable: Boolean} | 'auto' | 自定义    温馨提示：目录页数据依赖于结构化的侧边栏数据，如果你不设置为'structuring',将无法使用目录页

    // sidebarOpen: false, // 初始状态是否打开侧边栏，默认true
    updateBar: {
      // 最近更新栏
      showToArticle: false, // 显示到文章页底部，默认true
      // moreArticle: '/archives' // “更多文章”跳转的页面，默认'/archives'
    },
    // titleBadge: false, // 文章标题前的图标是否显示，默认true
    // titleBadgeIcons: [ // 文章标题前图标的地址，默认主题内置图标
    //   '图标地址1',
    //   '图标地址2'
    // ],

    pageStyle: "line", // 页面风格，可选值：'card'卡片 | 'line' 线（未设置bodyBgImg时才生效）， 默认'card'。 说明：card时背景显示灰色衬托出卡片样式，line时背景显示纯色，并且部分模块带线条边框

    // contentBgStyle: 1,

    category: false, // 是否打开分类功能，默认true。 如打开，会做的事情有：1. 自动生成的frontmatter包含分类字段 2.页面中显示与分类相关的信息和模块 3.自动生成分类页面（在@pages文件夹）。如关闭，则反之。
    tag: false, // 是否打开标签功能，默认true。 如打开，会做的事情有：1. 自动生成的frontmatter包含标签字段 2.页面中显示与标签相关的信息和模块 3.自动生成标签页面（在@pages文件夹）。如关闭，则反之。
    // archive: false, // 是否打开归档功能，默认true。 如打开，会做的事情有：1.自动生成归档页面（在@pages文件夹）。如关闭，则反之。

    author: {
      // 文章默认的作者信息，可在md文件中单独配置此信息 String | {name: String, href: String}
      name: "Evan Xu", // 必需
      href: "https://github.com/xugaoyi", // 可选的
    },
    social: {
      // 社交图标，显示于博主信息栏和页脚栏
      // iconfontCssFile: '//at.alicdn.com/t/font_1678482_u4nrnp8xp6g.css', // 可选，阿里图标库在线css文件地址，对于主题没有的图标可自由添加
      icons: [
        {
          iconClass: "icon-youjian",
          title: "发邮件",
          link: "mailto:894072666@qq.com",
        },
        {
          iconClass: "icon-github",
          title: "GitHub",
          link: "https://github.com/xugaoyi",
        },
        {
          iconClass: "icon-erji",
          title: "听音乐",
          link: "https://music.163.com/#/playlist?id=755597173",
        },
      ],
    },
    footer: {
      // 页脚信息
      createYear: 2019, // 博客创建年份
      copyrightInfo: "Evan Xu | MIT License", // 博客版权信息，支持a标签
    },
  },

  // 插件
  plugins: [
    ["fulltext-search"], // 全文搜索

    [
      "vuepress-plugin-baidu-tongji", // 百度统计
      {
        hm: baiduCode || "01293bffa6c3962016c08ba685c79d78",
      },
    ],

    [
      "one-click-copy",
      {
        // 代码块复制按钮
        copySelector: [
          'div[class*="language-"] pre',
          'div[class*="aside-code"] aside',
        ], // String or Array
        copyMessage: "复制成功", // default is 'Copy successfully and then paste it for use.'
        duration: 1000, // prompt message display time.
        showInMobile: false, // whether to display on the mobile side, default: false.
      },
    ],
    [
      "demo-block",
      {
        // demo演示模块 https://github.com/xiguaxigua/vuepress-plugin-demo-block
        settings: {
          // jsLib: ['http://xxx'], // 在线示例(jsfiddle, codepen)中的js依赖
          // cssLib: ['http://xxx'], // 在线示例中的css依赖
          // vue: 'https://jsd.cdn.zzko.cn/npm/vue/dist/vue.min.js', // 在线示例中的vue依赖
          jsfiddle: false, // 是否显示 jsfiddle 链接
          codepen: true, // 是否显示 codepen 链接
          horizontal: false, // 是否展示为横向样式
        },
      },
    ],
    [
      "vuepress-plugin-zooming", // 放大图片
      {
        selector: ".theme-vdoing-content img:not(.no-zoom)",
        options: {
          bgColor: "rgba(0,0,0,0.6)",
        },
      },
    ],
    [
      "@vuepress/last-updated", // "上次更新"时间格式
      {
        transformer: (timestamp, lang) => {
          const dayjs = require("dayjs"); // https://day.js.org/
          return dayjs(timestamp).format("YYYY/MM/DD, HH:mm:ss");
        },
      },
    ],
  ],

  markdown: {
    // lineNumbers: true,
    extractHeaders: ["h2", "h3", "h4", "h5", "h6"], // 提取标题到侧边栏的级别，默认['h2', 'h3']
  },
};

image-20231206215939559

# Gitee 部署

  • 部署流程跟上面 Vuepress 文档站点部署是一样样的：

配置远程仓库地址 -> 打包 -> 推送至远程仓库 -> 开启 Gitee Pages 服务

值得注意的是，不论是执行 yarn dev 还是 yarn build，都会有这样的友好提示（这也是和 Vuepress 不同的地方）：

image-20231206164726405

按提示修改就行

# 踩坑记录

  • 一晚上遇到好些个坑，在 config.js 配置文件中指定 base 路径并打包完成后，在 dist 目录下执行以下命令：
serve
  • 结果是这样（样式丢失）：（2023/12/06 晚）

image-20231206165305532

  • 这样是正常的，在推送 dist 目录下的文件到远程仓库的过程中，由于对 git 命令的不熟悉，一直被之前的提交记录所影响

  • 建议直接把打包后生成的 dist 目录剪切在一个干净的目录下，执行推送

  • 推送成功：

image-20231206221124915

  • 开启 Gitee Pages 服务成功后，直接访问：（2023/12/06 晚）

image-20231206221217820

image-20231206213451379

# Vdoing 主题搭建文档站点

# Memory Tools

  • 今日，Memory-Tools 开发者文档基本完成！效果如下：（2032/12/19 午）

image-20231219134202831

# MemorySearch 忆搜阁

今日，基本完成 MemorySearch 忆搜阁 的文档编写和网站首页制作！

网站首页使用 vuepress-theme-hope 主题：

image-20240219110401147

开发文档使用 vdoing 主题：

image-20240219110100681

使用 vdoing 主题搭建的 Vuepress 文档中，在 config.js 和 index.md 文件中，可分别修改文档首页 LOGO 和 导航栏 LOGO：

module.exports = {
  theme: "vdoing", // 使用依赖包主题
  // theme: require.resolve('../../vdoing'), // 使用本地主题 (先将vdoing主题文件下载到本地：https://github.com/xugaoyi/vuepress-theme-vdoing)
  title: "MemorySearch 开发者文档",
  description: "🚀为简化开发而生",
  base: "/memory-search-docs/", // 默认'/'。如果你想将你的网站部署到如 https://foo.github.io/bar/，那么 base 应该被设置成 "/bar/",（否则页面将失去样式等文件）
  // 主题配置
  themeConfig: {
    nav: [
      { text: "首页", link: "/" },
      {
        text: "操作指南",
        link: "/pages/52d5c3/",
        items: [
          { text: "概述", link: "/pages/52d5c3/" },
          { text: "系统设计", link: "/pages/a2f161/" },
          { text: "维护升级", link: "/pages/793dcb/" },
          {
            items: [
              { text: "高效多元搜索", link: "/pages/346f3e/" },
              { text: "互动创作平台", link: "/pages/94778b/" },
              { text: "流量统计分析", link: "/pages/c0261e/" },
              { text: "个人中心管理", link: "/pages/8dfa99/" },
              { text: "资源全面管理", link: "/pages/8dfab5/" },
            ],
          },
        ],
      },
      {
        text: "学习收获",
        link: "/pages/8dfad9/",
        items: [
          { text: "概览", link: "/pages/8dfad9/" },
          {
            items: [
              { text: "Ant Design Vue 脚手架", link: "/pages/advjsj/" },
              { text: "Vuepress 静态文档站点", link: "/pages/vpjtwd/" },

              { text: "数据抓取", link: "/pages/sjzq/" },
              { text: "Elastic Stack 技术栈", link: "/pages/esjsz/" },

              { text: "适配器模式", link: "/pages/apqms/" },
              { text: "门面模式", link: "/pages/mmms/" },
              { text: "注册器模式", link: "/pages/zcqms/" },

              { text: "关键词语高亮", link: "/pages/gjcygl/" },
              { text: "搜索词条建议", link: "/pages/ssctjy/" },
              { text: "热门搜索统计", link: "/pages/rmsstj/" },
              { text: "热门话题分析", link: "/pages/rmhtfx/" },

              { text: "Logstash 数据同步管道", link: "/pages/lssjtbgd/" },
              { text: "Canal 监控数据库流水", link: "/pages/cjksjkls/" },
              { text: "Kibana 数据监控面板", link: "/pages/ksjjkmb/" },

              { text: "限流策略", link: "/pages/xlcl/" },
              { text: "Redis 缓存优化", link: "/pages/rhcyh/" },
              { text: "Knife4j & Swagger 接口文档", link: "/pages/ksjkwd/" },

              { text: "定时任务调度", link: "/pages/dsrwdd/" },
              { text: "权限校验机制", link: "/pages/qxjyjz/" },
              { text: "异步编程支持", link: "/pages/ybbczc/" },
            ],
          },
        ],
      },
      // { text: "案例", link: "/pages/5d571c/" },
      {
        text: "问题答疑",
        link: "/pages/9cc27d/",
        items: [
          { text: "简介", link: "/pages/9cc27d/" },
          { text: "常见问题与解答", link: "/pages/9cc288/" },
        ],
      },
      // { text: "赞助", link: "/pages/1b12ed/" },
    ],
    sidebarDepth: 2, // 侧边栏显示深度，默认1，最大2（显示到h3标题）
    logo: "/img/logo.png", // 导航栏logo
    repo: "xugaoyi/vuepress-theme-vdoing", // 导航栏右侧生成Github链接
    searchMaxSuggestions: 10, // 搜索结果显示最大数
    lastUpdated: "上次更新", // 更新的时间，及前缀文字   string | boolean (取值为git提交时间)


---
home: true
heroImage: /img/logo.png
heroText: MemorySearch 开发者文档
tagline: 🚀为简化开发而生
actionText: 开始使用 →
actionLink: /pages/52d5c3/
bannerBg: none # auto => 网格纹背景(有bodyBgImg时无背景)，默认 | none => 无 | '大图地址' | background: 自定义背景样式       提示：如发现文本颜色不适应你的背景时可以到palette.styl修改$bannerTextColor变量

image-20240219105642175

# 严重问题

2024 年 4 月 29 日

image-20240429084945308

image-20240429085809381

image-20240429085813430

image-20240429090001153

欢迎访问：大道至简：快速搭建博客与文档站点的终极指南 2.0 - Memory's blog (atomgit.net) (opens new window)，学习更加全面的静态网站建站经验

OpenAPI 生成接口
基础信息管理

← 基础信息管理→

Theme by Vdoing | Copyright © 2023-2024 回忆如初