docsify 使用说明

Docsify 使用说明

此处仅做简略说明，如需详细了解请参考docsify官网

推荐全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。

npm i docsify-cli -g

初始化项目

如果想在项目的 ./docs 目录里写文档，直接通过 init 初始化项目。

docsify init ./docs

开始写文档

初始化成功后，可以看到 ./docs 目录下创建的几个文件

• index.html 入口文件
• README.md 会做为主页内容渲染
• .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

直接编辑 docs/README.md 就能更新文档内容，当然也可以添加更多页面。

本地预览

通过运行 docsify serve 启动一个本地服务器，可以方便地实时预览效果。默认访问地址 http://localhost:3000 。

docsify serve docs

说明：在文件根目录，通过运行 docsify serve 启动一个本地服务器，即：在docs根目录下执行docsify serve即可，如果在docs上级目录，可示例方式执行docsify serve docs启动本地服务器

关于文档书写

markdown文档书写工具，使用自己熟悉的工具即可，例如Typora

如果变更导航栏，则需要修改_navbar.md

如果变更侧边栏，则需要修改_sidebar.md，根据具体业务修改相关文件夹下的侧边栏文件即可

多页文档

如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 guide.md 文件，那么对应的路由就是 /#/guide。

假设你的目录结构如下：

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

那么对应的访问页面将是:

docs/README.md        => http://domain.com
docs/guide.md         => http://domain.com/guide
docs/zh-cn/README.md  => http://domain.com/zh-cn/
docs/zh-cn/guide.md   => http://domain.com/zh-cn/guide

重点文件说明

index.html：该文件内容最好不要修改，如需要修改请参考docsify官网修改相关配置

_sidebar.md:为侧边栏目录文件

_navbar.md:为导航栏目录文件

说明：创建 .nojekyll 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。

线上部署

nginx新增一下配置即可：

    server {
      listen       4006;
      server_name  localhost;
      location / {
        alias /opt/source/docs/;  
       index index.html;
      }
    }

history路由调整侧边栏

routerMode: 'history',
alias: {
  '/.*/_sidebar.md': function (_sidebar) {
    var basePath = _sidebar.match(/\/.*?\//)[0];
    var sideValue = basePath + '_sidebar.md';
    return sideValue;
  }, 
},

忽略编译链接

有时候我们会把其他一些相对路径放到链接上，你必须告诉 docsify 你不需要编译这个链接。 例如：

[link](/demo/ ':ignore')

即将会得到 <a href="/demo/">link</a> html 代码。不要担心，你仍然可以为链接设置标题。

如果链接为附件下载链接，也可使用此方式

[link](/demo/ ':ignore title')

<a href="/demo/" title="title">link</a>