Docsify文档搭建记录

Docsify
方法技能
发布日期:   2022-06-17

使用docsify部署自己的学习笔记库

Docsify Demo地址：https://xmq.plus/docs

docsify中文手册：https://docsify.js.org/#/zh-cn/

安装

安装docsify：

npm i docsify-cli -g

初始化：

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

docsify init ./docs

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

  • index.html 入口文件，可以对页面总体布局进行设置。
  • README.md 为主页内容渲染，直接编辑 docs/README.md 就能更新文档内容。
  • .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

本地预览：

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

docsify serve docs

配置

多页文档

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

假设你的目录结构如下：

.
└── docs
    ├── README.md
    ├── guide.md
    └── web
        ├── README.md
        ├── HTML.md
        └── CSS.md

那么对应的访问页面将是

docs/README.md            => http://domain.com
docs/guide.md             => http://domain.com/guide
docs/web/README.md      => http://domain.com/web/
docs/web/HTML.md          => http://domain.com/web/HTML.md
docs/web/CSS.md           => http://domain.com/web/CSS.md

定制侧边栏

为了获得侧边栏，您需要创建自己的_sidebar.md，你也可以自定义加载的文件名。默认情况下侧边栏会通过 Markdown 文件自动生成，效果如Typora的文档的侧边栏。

<!-- index.html -->

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

如果需要定义，则在所在目录下创建 _sidebar.md 文件，内容如下

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

* [首页](zh-cn/)
* [指南](zh-cn/guide)

需要在 ./docs 目录创建 .nojekyll 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。

显示目录层级

自定义侧边栏后默认不会再生成目录，你也可以通过设置生成目录的最大层级开启这个功能。

window.$docsify = {
  subMaxLevel: 2,
};

定制化

在index.html顶部加入

<link rel="icon" href="_media/favicon.ico" />

导航栏

如果你需要定制导航栏，可以用 HTML 创建一个导航栏。

注意：文档的链接都要以 #/ 开头。

<!-- index.html -->

<body>
  <nav>
    <a href="#/">EN</a>
    <a href="#/zh-cn/">中文</a>
  </nav>
  <div id="app"></div>
</body>

那我们可以通过 Markdown 文件来配置导航。首先配置 loadNavbar，默认加载的文件为 _navbar.md。

<!-- index.html -->

<script>
  window.$docsify = {
    loadNavbar: true
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<!-- _navbar.md -->

* [En](/)
* [简体中文](/zh-cn/)

你需要在 ./docs 目录下创建一个 .nojekyll 文件，以防止 GitHub Pages 忽略下划线开头的文件。

_navbar.md 加载逻辑和 sidebar 文件一致，从每层目录下获取。例如当前路由为 /zh-cn/custom-navbar 那么是从 /zh-cn/_navbar.md 获取导航栏。

如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式。

<!-- _navbar.md -->

* 入门

  * [快速开始](zh-cn/quickstart.md)
  * [多页文档](zh-cn/more-pages.md)
  * [定制导航栏](zh-cn/custom-navbar.md)
  * [封面](zh-cn/cover.md)


* 配置
  * [配置项](zh-cn/configuration.md)
  * [主题](zh-cn/themes.md)
  * [使用插件](zh-cn/plugins.md)
  * [Markdown 配置](zh-cn/markdown.md)
  * [代码高亮](zh-cn/language-highlight.md)

小屏设备下合并导航栏到侧边栏。

window.$docsify = {
  mergeNavbar: true,
};

侧边栏标题

文档标题，会显示在侧边栏顶部。

window.$docsify = {
  name: 'docsify',
};

name 项也可以包含自定义 HTML 代码来方便地定制。

window.$docsify = {
  name: '<span>docsify</span>',
};

添加页面标题

同时设置 loadSidebar 和 autoHeader 后，可以根据 _sidebar.md 的内容自动为每个页面增加标题。

window.$docsify = {
  loadSidebar: true,
  autoHeader: true,
};

添加文件更新时间

我们可以通过 {docsify-updated} 变量显示文档更新日期. 并且通过 formatUpdated配置日期格式。

window.$docsify = {
  formatUpdated: '{YYYY}-{MM}-{DD}',
};

然后在markdown文档需要添加更新时间的代码：{docsify-updated}。

替换主题色

替换主题色。利用 CSS3 支持变量的特性，对于老的浏览器有 polyfill 处理。

window.$docsify = {
  themeColor: '#2096ff'
};

更换主题

目前提供三套主题可供选择，模仿 Vue 和 buble 官网订制的主题样式。还有 @liril-net 贡献的黑色风格的主题。

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dolphin.css">

修改页面加载信息

初始化时会显示 Loading... 内容，可以自定义提示信息。

  <!-- index.html -->

  <div id="app">加载中</div>

emoji表情

可以在需要的位置添加emoji表情，Windows使用默认的微软输入法，使用WIN+.打开emoji表情库选择。

插件

全文搜索插件

HTML文件末尾添加js：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
window.$docsify = {     
    search: {
        paths: 'auto',
        placeholder: '🔍 Search',
        noData: '😒 No Result',
        // Headline depth, 1 - 6
        depth: 6,
        maxAge: 86400000, // 过期时间，单位毫秒，默认一天
      },//添加搜索框
    };

分页导航

docsify的分页导航插件，由@imyelo提供。

<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>

从这里获取更多信息。

window.$docsify = {
  // ...
  pagination: {
    previousText: '上一章节',
    nextText: '下一章节',
    crossChapter: true,
    crossChapterText: true,
  },
}

字体个人认为偏大，在index.html的<head></head>标签设置字体大小：

<style>
  .pagination-item-title {
    font-size: 1em !important;
  }
</style>

Tips

这个点击下一页后不能自动回到顶部，可以添加auto2top配置

切换页面后自动跳转到页面顶部。

window.$docsify = {
  auto2top: true,
};

字数统计

这是一款为docsify提供文字统计的插件. @827652549提供

它提供了统计中文汉字和英文单词的功能，并且排除了一些markdown语法的特殊字符例如*、-等

Add JS

<script src="//unpkg.com/docsify-count/dist/countable.js"></script>

Add settings

window.$docsify = {
  count:{
    countable:true,
    fontsize:'0.9em',
    color:'rgb(90,90,90)',
    language:'chinese'
  }
}

check document

代码高亮

docsify内置的代码高亮工具是 Prism。Prism 默认支持的语言如下：

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

添加额外的语法支持需要通过CDN添加相应的语法文件 :

<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>

文档记录的目前是HTML、CSS和JavaScript，目前够用，只需要添加一个bash即可。

缩放图片

引入js文件，

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

对需要缩放的图片进行如下设置

<img src="url" width="200" height="200" />

自定义插件

  • 自定义页脚信息

给每个页面的末尾加上 footer

window.$docsify = {
  plugins: [
    function(hook) {
      var footer = [
        '<hr/>',
        '<footer>',
        '<span><a href="https://github.com/QingWei-Li">cinwell</a> &copy;2017.</span>',
        '<span>Proudly published with <a href="https://github.com/docsifyjs/docsify" target="_blank">docsify</a>.</span>',
        '</footer>'
      ].join('');

      hook.afterEach(function(html) {
        return html + footer;
      });
    }
  ]
};

Mermaid图表

借助Mermaid实现markdown中绘制图表，需要增加如下脚本。

参考来源：

mermaid官网文档首页：https://mermaid-js.github.io/mermaid/#/

<head>标签添加脚本（脚本放 尾部标签不生效）：

  <!-- mermaid插件 -->
  <script src="//cdn.jsdelivr.net/npm/mermaid@9.1.6/dist/mermaid.min.js"></script>
  <style>
    .markdown-section {
      max-width: 1200px;
    }
  </style>

配置项添加：

<script>
    window.$docsify = {
        // mermaid配置
        markdown: {
            renderer: {
                code: function (code, lang) {
                    if (lang && (lang.startsWith('mermaid') || lang === 'mmd')) {
                        var resultingHTML = '';
                        if (lang === 'mmd' || lang === 'mermaid-example') {
                            currentCodeExample++;
                            colorize.push(currentCodeExample);
                            resultingHTML +=
                                '<pre id="code' + currentCodeExample + '">' + escapeHTML(code) + '</pre>';
                        }
                        if (lang === 'mermaid' || lang === 'mermaid-example') {
                            resultingHTML +=
                                '<div class="mermaid">' + mermaid.render('mermaid-svg-' + num++, code) + '</div>';
                        }
                        if (resultingHTML !== '') {
                            return resultingHTML;
                        }
                    }
                    return this.origin.code.apply(this, arguments);
                },
            },
        }
    };
    // mermaid配置
    var num = 0;
    const isDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches;
    const conf = {
      logLevel: 4,
      startOnLoad: false,
      themeCSS: '.label { font-family: Source Sans Pro,Helvetica Neue,Arial,sans-serif; }.node rect { fill: #fff;stroke: #333;stroke-width: 1px;color: #333; }',
      flowchart: {
        curve: 'linear',  // 'basis', 'linear', 'cardinal'
      }
    };
    if (isDarkMode) conf.theme = 'dark';
    mermaid.initialize(conf);
</script>

自动标题编号

给markdown文档标题自动添加编号标题。

参考来源：

docsify-autoHeaders：https://github.com/markbattistella/docsify-autoHeaders

index.html文件下引入资源，可选unpkg，jsdeliver、本地三种引入方式：

<!-- unpkg.com -->
<script src="https://unpkg.com/@markbattistella/docsify-autoheaders@latest"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@markbattistella/docsify-autoheaders@latest"></script>

<!-- locally -->
<script src="docsify-autoheaders.min.js"></script>

配置项设置示例，具体配置说明查看插件文档：

window.$docsify = {
      autoHeaders: {
        separator: 'decimal',
        levels: {
          start: '1',
          finish: '3'
        },
        scope: '#main',
        debug: false
      },
};

给需要设置自动编号的md文件在顶部添加：@autoHeader:#配置，例如，@autoHeader:1.1.1，给1-3级标题从1开始自动标号。

回到顶部按钮

项目地址：sumsung524/docsify-backTop

页面末尾引入JS文件：

<script src="https://cdn.jsdelivr.net/gh/Sumsung524/docsify-backTop/dist/docsify-backTop.min.js"></script>
<script>
    var docsifyBackTop = {
        size: 32,
        bottom: 15,
        right: 15,
        logo: '<svg t="1662288563130" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="3633" width="200" height="200"><path d="M513 103.7c-226.1 0-409.4 183.3-409.4 409.4S286.9 922.6 513 922.6s409.4-183.3 409.4-409.4S739.1 103.7 513 103.7z m153.5 364.7c-5.2 5.3-12.1 7.9-19 7.9s-13.8-2.6-19-7.9L545.1 385c0 0.4 0.1 0.7 0.1 1.1V705c0 11.1-5.7 20.9-14.4 26.6-4.7 4.2-10.9 6.7-17.7 6.7-6.8 0-13-2.5-17.7-6.7-8.7-5.7-14.4-15.5-14.4-26.6V386.1c0-0.4 0-0.7 0.1-1.1l-83.4 83.4c-10.5 10.5-27.5 10.5-38 0s-10.5-27.5 0-38L494 295.9c10.5-10.5 27.5-10.5 38 0l134.5 134.5c10.5 10.4 10.5 27.5 0 38z" fill="#2096ff" p-id="3634"></path></svg>',
        bgColor: ''
    };
</script>

CDN

推荐使用 jsDelivr，能及时获取到最新版。你也可以在cdn.jsdelivr.net/npm/docsify/中浏览npm包的源代码。

部署

Gitee创建一个docs仓库，将本地的docs上传，打开gitee pages服务，部署目录填入/即可。

获取最新版

不指定特定版本号时将引入最新版。

<!-- 引入 css -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">

<!-- 引入 script -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.js"></script>

也可以使用 压缩版文件.

获取指定版

如果担心频繁地版本更新又可能引入未知 Bug，我们也可以使用具体的版本。规则是 //cdn.jsdelivr.net/npm/docsify@VERSION/

<!-- 引入 css -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4.10.2/themes/vue.css">

<!-- 引入 script -->
<script src="//cdn.jsdelivr.net/npm/docsify@4.10.2/lib/docsify.js"></script>

指定 VERSION 为 latest 可以强制每次都请求最新版本。

压缩版

CSS 的压缩文件位于 /lib/themes/ 目录下，JS 的压缩文件是原有文件路径的基础上加 .min 后缀。

<!-- 引入 css -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">

<!-- 引入 script -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<!-- 引入 css -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4.10.2/lib/themes/vue.css">

<!-- 引入 script -->
<script src="//cdn.jsdelivr.net/npm/docsify@4.10.2/lib/docsify.min.js"></script>

其他CDN

index.html

为了记录对初始化后的docsify改动内容，下面经过上述记录形成的index.html。

<!DOCTYPE html>
<html lang="zh-CN">

<head>
  <meta charset="UTF-8">
  <title>Docs</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
  <!-- 最新版主题样式： -->
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
  <!-- 黑色主题样式： -->
  <!-- <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css"> -->
</head>
<!-- 调整分页导航插件中字体显示偏大效果 -->
<style>
  .pagination-item-title {
    font-size: 1em !important;
  }
</style>

<body>
  <!-- 设置导航栏 -->
  <nav>
    <a href="#/">文档首页</a>
  </nav>
  <!-- 设置加载时显示内容 -->
  <div id="app">加载中</div>
  <script>
    window.$docsify = {
      loadSidebar: true,// 定制侧边栏，默认定制内容在当前目录的_sidebar.md内
      name: '',
      repo: '',
      subMaxLevel: 3,// 设置生成目录的最大层级开启这个功能。
      loadNavbar: true,// 设置导航栏，默认定制内容在当前目录的_navbar.md内
      // coverpage: true, 设置封面，默认定制内容在当前目录的_coverpage.md内
      name: 'Docs',//设置侧边栏标题
      nameLink: '/',//点击文档标题后跳转的链接地址。
      //logo: '36x.png',设置侧边栏图片logo
      themeColor: '#2096ff',//替换主题色
      // 添加页面标题
      loadSidebar: true,
      autoHeader: true,
      // 字数统计插件配置项
      count: {
        countable: true,
        fontsize: '0.9em',
        color: 'rgb(90,90,90)',
        language: 'chinese'
      },
      // 复制代码插件配置项
      copyCode: {
        buttonText: 'Copy',
        errorText: 'X',
        successText: '√'
      },
      // 分页导航插件配置项
      pagination: {
        previousText: '上一章节',
        nextText: '下一章节',
        crossChapter: true,
        crossChapterText: true,
      },  
      // 切换页面自动回到顶部
      auto2top: true,
      search: {
        paths: 'auto',
        placeholder: '🔍 Search',
        noData: '😒 No Result',
        // Headline depth, 1 - 6
        depth: 6,
        maxAge: 86400000, // 过期时间，单位毫秒，默认一天
      },//添加搜索框
      //开发插件，自制页脚版权
      plugins: [
        function (hook) {
          var footer = [
            // '<hr/>',
            '<footer>',
            '<br/><span>Copyright &copy;2022.&nbsp;&nbsp;Published by <a href="https://xmq.plus/" target="_blank">xmq.plus</a>.<br/></span>',
            '<span>湘ICP备2020018001号</span>',
            '</footer>'
          ].join('');

          hook.afterEach(function (html) {
            return html + footer;
          });
        }
      ]
    }
  </script>
  <!-- Docsify v4 -->
  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
  <!-- 字数统计插件 -->
  <script src="//unpkg.com/docsify-count/dist/countable.js"></script>
  <!-- 复制代码插件 -->
  <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
  <!-- 复制代码插件最新版本-->
  <!-- <script src="https://unpkg.com/docsify-copy-code"></script> -->
  <!-- 分页导航插件 -->
  <script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
  <!-- bash代码高亮 -->
  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
  <!-- 全文搜索插件： -->
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

</body>

</html>

参考文档

Docsify
赏
评论
 上一篇
Docsify返回顶部插件开发-docsify-backTop Docsify返回顶部插件开发-docsify-backTop
一个docsify文档的返回顶部插件，同时适用于其他需要添加回到顶部组件的所有页面。 项目地址：docsify-backTop Demo地址：docsify backTop Demo 开发原因docsify文档插件众多中，没有实现返回顶部功
2022-09-05 方法技能
Docsify
下一篇 
Gitbook文档系统搭建记录 Gitbook文档系统搭建记录
想搭建一个文档系统来记录学习笔记。 通过搭建Gitbook将markdown渲染成wiki文档并上传至服务器 。 安装Node.js使用Gitbook需要配置Node.js环境。同时，由于Gitbook兼容性问题，高版本node.js不可用
2022-06-16 方法技能
Gitbook
  目录