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

npm i docsify-cli -g

老马啸西风2021年10月12日大约 1 分钟

docsify-02-多页

如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。

例如创建一个 guide.md 文件，那么对应的路由就是 /#/guide。

假设你的目录结构如下：

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

老马啸西风2021年10月12日大约 5 分钟

docsify-03-配置项

你可以配置在 window.$docsify 里。


  window.$docsify = {
    repo: 'docsifyjs/docsify',
    maxLevel: 3,
    coverpage: true,
  };

老马啸西风2021年10月12日小于 1 分钟

docsify-04-主题 theme

目前提供三套主题可供选择，模仿 Vue 和 buble 官网订制的主题样式。

还有 @liril-net 贡献的黑色风格的主题。

老马啸西风2021年10月12日小于 1 分钟

docsify-05-插件 plugins

全文搜索插件会根据当前页面上的超链接获取文档内容，在 localStorage 内建立文档索引。

默认过期时间为一天，当然我们可以自己指定需要缓存的文件列表或者配置过期时间。


  window.$docsify = {
    search: 'auto', // 默认值

    search : [
      '/',            // => /README.md
      '/guide',       // => /guide.md
      '/get-started', // => /get-started.md
      '/zh-cn/',      // => /zh-cn/README.md
    ],

    // 完整配置参数
    search: {
      maxAge: 86400000, // 过期时间，单位毫秒，默认一天
      paths: [], // or 'auto'
      placeholder: 'Type to search',

      // 支持本地化
      placeholder: {
        '/zh-cn/': '搜索',
        '/': 'Type to search'
      },

      noData: 'No Results!',

      // 支持本地化
      noData: {
        '/zh-cn/': '找不到结果',
        '/': 'No Results'
      },

      // 搜索标题的最大层级, 1 - 6
      depth: 2,

      hideOtherSidebarContent: false, // 是否隐藏其他侧边栏内容

      // 避免搜索索引冲突
      // 同一域下的多个网站之间
      namespace: 'website-1',

      // 使用不同的索引作为路径前缀（namespaces）
      // 注意：仅适用于 paths: 'auto' 模式
      //
      // 初始化索引时，我们从侧边栏查找第一个路径
      // 如果它与列表中的前缀匹配，我们将切换到相应的索引
      pathNamespaces: ['/zh-cn', '/ru-ru', '/ru-ru/v1'],

      // 您可以提供一个正则表达式来匹配前缀。在这种情况下，
      // 匹配到的字符串将被用来识别索引
      pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/
    }
  }

老马啸西风2021年10月12日大约 4 分钟

docsify-06-自定义开发插件

docsify 提供了一套插件机制，其中提供的钩子（hook）支持处理异步逻辑，可以很方便的扩展功能。

完整功能

window.$docsify = {
  plugins: [
    function(hook, vm) {
      hook.init(function() {
         // 初始化完成后调用，只调用一次，没有参数。
      });

      hook.beforeEach(function(content) {
        // 每次开始解析 Markdown 内容时调用
        // ...
        return content;
      });

      hook.afterEach(function(html, next) {
        // 解析成 html 后调用。
        // beforeEach 和 afterEach 支持处理异步逻辑
        // ...
        // 异步处理完成后调用 next(html) 返回结果
        next(html);
      });

      hook.doneEach(function() {
        // 每次路由切换时数据全部加载完成后调用，没有参数。
        // ...
      });

      hook.mounted(function() {
        // 初始化并第一次加载完成数据后调用，只触发一次，没有参数。
      });

      hook.ready(function() {
        // 初始化并第一次加载完成数据后调用，没有参数。
      });
    }
  ]
};

老马啸西风2021年10月12日大约 1 分钟

docsify-07-Markdown 配置

内置的 Markdown 解析器是 marked，可以修改它的配置。

同时可以直接配置 renderer。

window.$docsify = {
  markdown: {
    smartypants: true,
    renderer: {
      link: function() {
        // ...
      }
    }
  }
}

老马啸西风2021年10月12日小于 1 分钟

docsify-08-代码高亮

docsify内置的代码高亮工具是 Prism。

Prism 默认支持的语言如下：

Markup - markup, html, xml, svg, mathml, ssml, atom, rss
CSS - css
C-like - clike
JavaScript - javascript, js

老马啸西风2021年10月12日小于 1 分钟

PanDoc-文档类型转换神器

手写了一个生成 markdown 格式文档的工具。

但是公司有时候需要 word 类型的文档，有时候我们又需要 pdf 格式的文档。

方式一：自己造轮子

为每一种转换都写一种实现，但是很消耗时间。

而且看了 word 的相关生成，也不是很友好。

会导致迭代周期变得非常长。

方式二：让专业的人做专业的事

以前使用过 Typora 等 md 编辑器，知道 markdown 可以导出各种类型的文件。

我就没必要再重复一次。

PanDoc

Typora 等诸多文件的转换，底层都是使用了 PanDoc

老马啸西风2019年3月16日大约 3 分钟

reStructuredText 标记语言语法入门介绍

reStructuredText 是一种易于阅读的、看到的就是得到的纯文本标记语法和解析器系统。它对于内联程序文档(如Python文档字符串)、快速创建简单web页面和独立文档非常有用。reStructuredText设计用于特定应用程序领域的可扩展性。reStructuredText解析器是Docutils的一个组件。reStructuredText是对StructuredText和Setext轻量级标记系统的修改和重新解释。

老马啸西风2018年11月10日小于 1 分钟