推荐一款好用的文档工具：docsify

docsify是什么

docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 index.html 就可以开始编写文档并直接部署在 GitHub Pages。编写一些团队内部研发规范、api接口文档等非常方便，如果想要系统的学习，还是推荐查阅： docsify官网

特性

• 无需构建，写完文档直接发布
• 容易使用并且轻量 (压缩后 ~21kB)
• 智能的全文搜索
• 提供多套主题
• 丰富的 API
• 支持 Emoji
• 兼容 IE11
• 支持服务端渲染 SSR (示例)

开始使用

• 安装node.js ，安装过程不作介绍，直接安装最新的 LTS 版本即可，node.js官网

• 全局安装 docsify-cli

  npm i docsify-cli -g
  

• 初始化项目

  docsify init ./docs
  

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

  • index.html 入口文件

  • README.md 会做为主页内容渲染

  • .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

    直接编辑 docs/README.md 就能更新文档内容，

本地运行

docsify serve docs

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

注：是在 docs 所在的目录执行，不是在 docs 里面。

侧边栏_sidebar.md

• 配置index.html

  <!-- 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)
  

• 预览

导航栏

• 配置 index.html 文件

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

• 创建 _navbar.md 文件

  <!-- _navbar.md -->
  
  * [En](/)
  * [简体中文](/zh-cn/)
  

• 预览

主题

更换主题非常简单，只需要在 index.html 页面，引入样式即可

<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">

部署

请查阅：docsify部署

结语

本文简单介绍了 docsify 的使用，其他详细配置请查阅：docsify官网