计算机基础 | 文档神器docsify安装及基本使用

为啥要用docsify？

神器Docsify让你的文档变得美观，配合typora，从此爱上看文档，各种优点：小巧、快速、美观、方便、快捷、上手快，可以浏览如下优秀案例

• ve-charts
• pyecharts
• pyecharts-gallery
• 处于萌芽阶段的 Java 核心知识库

更多案例请看：Awesome Docsify

安装

1、首先安装npm：

sudo apt install npm

如果报错，则执行如下命令安装相关依赖

sudo apt-get install nodejs-dev node-gyp libssl1.0-dev

然后再执行安装命令：

sudo apt install npm

2、安装docsify-cli:

npm i docsify-cli -g

基本使用

1、初始化项目：

在项目的文档记录文件./docs目录里写文档，通过init初始化项目

docsify init ./docs

初始化成功后，在./docs目录会有如下几个文件

• index.html，这是入口文件，不做解释

• README.md，主页内容，不做解释

• .nojekyll ，这是用于阻止Github Pages忽略掉下划线开头的文件

2、本地预览网站

docsify serve docs

默认访问：http://localhost:3000/

如需修改端口号：

docsify serve docs --port=3001

进一步优化

如何添加侧边栏呢？

1、首先在index.html中将loadSidebar设置为true：

<!-- index.html -->

<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

2、创建_sidebar.md

<!-- docs/_sidebar.md -->

* [Home](/)
* [Guide](guide.md)

注：如果要上传到Github Pages的话，需要在./docs中包含.nojekyll

文档结构大致如下：

└── docs/
    ├── _sidebar.md
    ├── .nojekyll
    ├── index.html
    ├── getting-started.md
    └── running-services.md

设置目录展开级别，在index.html中设置subMaxLevel即可：

<!-- index.html -->

<script>
  window.$docsify = {
    loadSidebar: true,
    subMaxLevel: 2
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

如何添加各种插件呢？

1、 添加全文搜索插件：

<script>
  window.$docsify = {
    search: 'auto', // default

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

    // complete configuration parameters
    search: {
      maxAge: 86400000, // Expiration time, the default one day
      paths: [], // or 'auto'
      placeholder: 'Type to search',

      // Localization
      placeholder: {
        '/zh-cn/': '搜索',
        '/': 'Type to search'
      },

      noData: 'No Results!',

      // Localization
      noData: {
        '/zh-cn/': '找不到结果',
        '/': 'No Results'
      },

      // Headline depth, 1 - 6
      depth: 2,

      hideOtherSidebarContent: false, // whether or not to hide other sidebar content

      // To avoid search index collision
      // between multiple websites under the same domain
      namespace: 'website-1',

      // Use different indexes for path prefixes (namespaces).
      // NOTE: Only works in 'auto' mode.
      //
      // When initialiazing an index, we look for the first path from the sidebar.
      // If it matches the prefix from the list, we switch to the corresponding index.
      pathNamespaces: ['/zh-cn', '/ru-ru', '/ru-ru/v1'],

      // You can provide a regexp to match prefixes. In this case,
      // the matching substring will be used to identify the index
      pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/
    }
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

2、添加代码复制插件：

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>

3、添加latex公式插件:

<script src="//cdn.jsdelivr.net/npm/docsify-katex@latest/dist/docsify-katex.js"></script>
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css"/>

更多插件可以参考：Awesome docsify plugins

参考

• 在ubuntu安装npm
• docsify(和gitbook一样的好东西)
• docsify文档
• mkdocs