docsify

安装与部署

安装

首先要安装 nodejs ，之后通过命令 npm i docsify-cli -g 安装

创建仓库

docsify init ./vue3Docs 会在当前目录下创建名称为 vue3Docs 的目录并作为 docsify 的仓库，cli 会在该目录下创建两个文件：index.html - 入口文件
README.MD - 内容文件

运行项目

在 cmd 中切换路径到 vue3Docs 的上级目录，使用命令 docsify serve vue3Docs 运行项目

部署到VPS

1. 保证 VPS 中安装 nodejs，并安装 docsify

2. 将 docsify 项目目录拷贝到 VPS 指定目录，然后在 nginx 中设置映射关系

   location /kb {
       alias /projs/docsify/knowledgeBase/;
       index index.html;
       try_files $uri $uri/ /index.html;
   }
   

3. 注意所有 markdown 文件的后缀名要求小写 md，并设置项目主页文件 index.html 代码如下：(关键代码是 alias 的配置)

   window.$docsify = {
     name: '',
     repo: '',
     loadSidebar: true,
     auto2top: true,
     subMaxLevel: 2,
     alias: { '/.*/_sidebar.md': '/_sidebar.md'},
   }
   

使用案例

项目根目录

在其他子页面中使用超链接 '点我进入开发手册' 表示跳转页面到项目根目录，项目会访问 README.md

多页面跳转

如果设置的超链接是 '点我进入guide.md' 圆括号中不需要写 markdown 文件的后缀名，表示跳转到项目根目录下的文件 guide.md

侧边导航菜单

在项目根目录下创建文件 _sidebar.md 作为项目的侧边导航菜单，要求在 index.html 中做对应配置（第五行）

  <script>
    window.$docsify = {
      name: '',
      repo: '',
      loadSidebar: true
    }
  </script>

location /handbook {
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_pass http://localhost:3000/;
}

错误与提示

子页面显示404

windows系统中忽略大小写，但是 linux 中严格区分，所以注意 markdown 文件的后缀名要求是小写的 md，同时由于左侧树形菜单官方的默认文件名是 _sidebar.md ，需要在项目首页文件 index.html 做配置项 alias: { '/.*/_sidebar.md': '/_sidebar.md'}，完整的代码如下

window.$docsify = {
    name: '',
    repo: '',
    loadSidebar: true,
    auto2top: true,
    subMaxLevel: 2,
    alias: { '/.*/_sidebar.md': '/_sidebar.md'},
}