几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

Author：安。
发布时间：November 22, 2021
2401 views
No comments
7758 words
Categories：软硬兼施

## 文档框架

同博客框架 WordPress、Hexo 等一样，Web 文档也有自己的框架，如比如 Java 的 Javadoc，Python 的 pydoc，以及Python-sphinx。对于 Python 有专门文档标记语言 reStructuredText（RST），常见的 Python 各种库和工具的帮助文档基本都是用 RST 所写。如 Requests、Flask、Scrapy 等。
![](https://assets.guaishow.cn/Picgo/20211122153151.png)
不过，用 RST 编写对于已经会了 Markdown（更为流行） 的读者来说，有点浪费，而且两者的语法差异较大，容易造成记忆冲突。幸运的是有了 mkdocs，不仅能轻松制作类似 Scrapy 帮助文档的文档项目，而且支持 markdown 语法。

### 使用MkDocs

#### 安装 MkDocs

```
pip install mkdocs
```

#### 创建项目

执行下面命令就在当前目录下，生成一个 testdocs 文件夹，就是创建的文档项目

```
mkdocs new testdocs
```

cd命令进入文件夹，查看结构
![](https://assets.guaishow.cn/Picgo/20211122153304.png)

* mkdocs.yml 为配置文件
* docs 文件夹中为文档文件目录，文件使用 markdown 编写

#### 文档预览

进入 创建的文档项目目录，执行 `mkdocs serve`：

```
mkdocs serve

INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.16 seconds
INFO     -  [18:16:18] Serving on http://127.0.0.1:8000/
```

将启动一个 Web 服务器，用于预览 testdocs 文件项目，效果如下：
将启动一个 Web 服务器，用于预览 testdocs 文件项目，效果如下：
![](https://assets.guaishow.cn/Picgo/20211122162027.png)

#### 进行配置

mkdocs 的配置简单明了，采用 yml 格式：

```
site_name: MkLorum
site_url: https://example.com/
nav:
    - Home: 'index.md'
    - About: 'markdown.md'
theme: readthedocs
```

当文档比较复杂时，可以通过嵌套的方式对 nav 进行配置，例如在 Home 下还有子菜单，menu1 和 menu2：

```
nav:
    - Home: 'index.md'
    - 'User Guide':
        - 'Writing your docs':
            - Menu1 : 'menu1.md'
            - Menu2 : 'menu2.md'
        - 'Styling your docs': './style/styling-your-docs.md'
    - About:
        - 'License': 'license.md'
        - 'Release Notes': 'release-notes.md'
```

效果如下：
![](https://assets.guaishow.cn/Picgo/20211122162206.png)

* 如果菜单名中有空格需要用引号(单双皆可)括起来
* 文档文件不要同导航结构配合，可以为导航配置相对文件路径
* 菜单层级可以无限嵌套
* `默认情况下，即在不配置导航 (nav) 的情况下，会按照文件名，目录结构生成导航菜单`

#### 更换主题

下载主题：

```
pip **install** mkdocs-material mkdocs-windmill
```

mkdocs.yml里添加:

```
theme:
  name: 'material'
# 也可以选bootstrap
```

其他的一些配置：

```
theme:
  name: "material"
  # logo: 'images/logo.svg'
  logo:
      icon: "mkdocs"
  palette:
      primary: "black"
      accent: "deep orange"
  language: "zh"
```

material页面风格：
![](https://assets.guaishow.cn/Picgo/20211122162408.png)

#### 更多主题：https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

#### 一些约定

* 站点首页 默认情况下，必须创建一个 index.md 作为站点首页。同时也支持 README.md 作为首页，会将其转化为 index.html。如果 index.md 和 README.md 同时存在，将忽略 README.md
* 非 markdown 文件 markdown 文件，即扩展名为 md 的文件，会被转化为 html。非 markdown 文件，会被原封拷贝，不做任何修改
  * 内部链接 如果需要引用另一个文件，只需要按照 markdown 链接的方式，连接到这个文件就可以了，例如 [详情请参考](./detail.md)。不要担心文件名，因为生成站点时会自动换成 html 文件路径

#### 生成站点

执行mkdocs build命令，生成站点，点击index.html即可

```
mkdocs build
```

### 使用sphinx

#### 安装sphinx和主题

```
pip install sphinx sphinx_rtd_theme
```

#### 创建项目

创建一个文件夹后，执行命令

```
sphinx-quickstart
```

#### 编写文档

![](https://assets.guaishow.cn/Picgo/20211122162733.png)

#### 修改主题

在conf.py文件中添加这两行代码，修改主题

```
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'

# 记得删除下面的html_theme = 'alabaster'
```

更多主题请参考：[https://sphinx-themes.org/](https://sphinx-themes.org/)

#### 构建站点

在根目录输入命令，即可生成网站构建。在build/html目录下即可看到生成的网站

```
make html
```

点击index.html即可查看
![](https://assets.guaishow.cn/Picgo/20211122162830.png)

### 使用Teadocs

Teadocs 是一款能够帮你快速构建html文档的工具，它基于nodejs编写，并使用markdown来编写文档内容。

Teadocs 提供内置的搜索技术，除了编写好你引以为豪的内容以外，你无需关注的任何额外的技术问题。

你可以使用它来编写开源书籍、API文档学习、笔记、学习心得、甚至可以用来写博客。

#### 安装

需要nodejs版本 >= 8.0，npm 版本 > 3.

```
$ npm install -g teadocs
```

初始化一个文档项目

```
$ teadcos init mydocs
```

进入这个文档目录

```
$ cd mydocs
```

此步骤是进入文档编辑模式（开发模式），此模式将监视markdown文件的变化，实时热替换html页面。

```
$ teadocs dev
```

#### 自动生成项目初始结构

如果你想偷懒，[那么你可以在编写好tree.md](http://xn--tree-uj5fo6auyd4kzpg0tjxzg7x0kxx1b.md/)（菜单的配置文件）的情况下，直接运行以下命令，teadocs可以自动帮你生成md文件。

```
$ teadocs init
```

### 编译成html

```
$ teadocs build
```

#### 文档目录结构介绍

```
testdocs
├─ build  #这个是编译输出的目录
│    ├─ config
│    │    ├─ main.html
│    │    ├─ nav.html
│    │    └─ structure.html
│    ├─ custom_theme.html
│    ├─ data.js
│    ├─ deploy.html
│    ├─ index.html
│    ├─ install.html
│    ├─ quick_start.html
│    ├─ static
│    │    ├─ css
│    │    ├─ font-awesome-4.7.0
│    │    ├─ fonts
│    │    ├─ images
│    │    └─ js
│    └─ template_markdown.html
├─ docs #这个是文档的源文件目录，也就是markdown文件目录。
│    ├─ config
│    │    ├─ main.md
│    │    ├─ nav.md
│    │    └─ structure.md
│    ├─ custom_theme.md
│    ├─ deploy.md
│    ├─ index.md
│    ├─ install.md
│    ├─ quick_start.md
│    └─ template_markdown.md
├─ static # 这个地方是用于存放文档中需要用要的静态文件，例如图片等，它会自动copy到build目录下。
|
├─ teadocs.config.js # 这是teadocs的主配置文件
└─ tree.html # 这是文档的菜单配置文件
```

#### 主配置文件说明

菜单的配置文件是你文档根目录下面的 `teadocs.config.js`，它是一个javascript的文件。

主配置文件的所有配置项都不是必填你完全可以什么也不填写，它的代码如下：

```
'use strict';
const path = require('path')

module.exports = {
    doc: {
        name: "", //文档名称
        description: "", //文档的描述
        version: "", //文档的版本
        dir: "", //文档的目录
        outDir: "", //文档编译成html时输出的目录
        staticDir: "" //文档所用到的静态文件的地址
    }, 
    theme: {
        dir: "", //主题的目录，可自定义主题
        title: "", //html的title标签
        headHtml: "", //html head 的代码
        footHtml: "", //html 底部 的代码
        isMinify: true, //是否为输出的html启用压缩
        rootPath: "/" //表示根路径，如果部署在深目录下面，这个配置项必填，不然会出现找不到资源路径的错误。
    },
    nav: {
        tree: "./tree"
    }
}
```

#### 默认配置

```
module.exports = {
    doc: {
        name: "欢迎使用Teadocs文档生成系统",
        description: "欢迎使用Teadocs文档生成系统",
        version: "0.0.1",
        dir: "./docs",
        outDir: "./build",
        staticDir: "./static"
    },
    theme: {
        dir: __dirname + '/../themes/default',
        title: "欢迎使用Teadocs文档生成系统",
        headHtml: `
        <meta name="description" content="欢迎使用Teadocs文档生成系统" />
        <meta name="keywords" content="teadocs, 文档生成器" />
        `,
        footerHtml: "",
        isMinify: false,
        rootPath: "/"
    },
    nav: {
        tree: "<ul><li><a>欢迎使用Teadocs文档生成系统</a></li></ul>"
    }
}
```

#### 菜单配置文件说明

菜单的配置文件是你文档根目录下面的 `tree.md` 文件，它采用了markdown语法来进行书写。

###### 菜单结构

例如，本文档的菜单结构如下：

```
- [介绍](/index)
- [快速入门](/quick_start)
- [安装](/install)
- +配置介绍
    - [文档目录结构介绍](/config/structure)
    - [主配置文件说明](/config/main)
    - [菜单配置文件说明](/config/nav)
- [markdown模版](/template_markdown)
- [自定义主题](/custom_theme)
- [部署](/deploy)
```

##### 符号介绍

语法完全使用markdown里的无序列表定义语法，但是要特别注意以下几点：

[] 里的内容表示菜单的标题，如果不写[]则代表这个菜单没有链接仅作为一个菜单名称。
() 里的内容表示菜单的markdown文件的地址，并且也代表了生成后的html文件url。

+ 代表了在生成的html里默认展开这个菜单，需要注意的是，这不是markdown的语法，这是teadocs的规定，+一定要写在文本的前面，而不是[的前面

#### markdown模版

你编写的markdown文件可以使用内置的ejs模版引擎，比如我们可以轻而易举的写个循环，像这样：

```
**<** **%** **[****1****,****2****,****3****,****4****]****.****forEach****(****function** **(****)** **{** **%** **>**
**-** 欢迎使用Teadocs文档生成工具
**<** **%** **}****)** **%** **>**
```

效果：

<% [1,2,3,4].forEach(function () { %>

* 欢迎使用Teadocs文档生成工具
  <% }) %>

#### 自定义主题

你可以构建自己的主题文件，只要符合Teadocs的主题规范，具体可以自行参考默认主题。

如何使用自己构建的主题？
在 teadocs.config.js 文件的 theme.dir 配置项中指定你的自定义主题路径就可以了。

#### 部署

##### 上传到github

可以你的文档源文件上传到github上，使用 .gitignore 屏蔽 ./build 目录。

##### 上传到服务器

建议使用nginx等静态服务器软件搭建一个静态服务器进行访问即可。

##### 运行项目结果

```
teadocs dev
```

默认端口号是3210
![](https://assets.guaishow.cn/Picgo/20211122163913.png)

### docsify

[https://docsify.js.org/#/zh-cn/](https://docsify.js.org/#/zh-cn/)
docsify是一个超级好用的文档站点生成器！特点是使用简单，跟着官网教程输入两行命令就能完成安装和生成站点了，生成的文档样式也很精简优雅，并且是响应式的，手机上看也很不错。
![](https://assets.guaishow.cn/Picgo/20211122162903.png)

### Dumi

https://d.umijs.org/zh-CN

阿里推出的文档站点生成工具，也是输入几行命令就能得到文档网站。和 docsify 不同的是，Dumi 专为 组件开发 场景而生，很适合作为组件库的文档。可以嵌入和折叠代码块、提供组件在终端中的浏览效果等，Dumi 生成的网站很精简，而且封面支持自定义特性的展示，因此也很适合作为项目或产品的官方文档。
![](https://assets.guaishow.cn/Picgo/20211122162925.png)

Last modification：November 22, 2021

如果觉得我的文章对你有用，请帮忙点一下上面的广告

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

安。 • 2021 年 11 月 22 日

## 文档框架

### 使用MkDocs

#### 安装 MkDocs

```
pip install mkdocs
```

#### 创建项目

执行下面命令就在当前目录下，生成一个 testdocs 文件夹，就是创建的文档项目

```
mkdocs new testdocs
```

cd命令进入文件夹，查看结构
![](https://assets.guaishow.cn/Picgo/20211122153304.png)

* mkdocs.yml 为配置文件
* docs 文件夹中为文档文件目录，文件使用 markdown 编写

#### 文档预览

进入 创建的文档项目目录，执行 `mkdocs serve`：

```
mkdocs serve

INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.16 seconds
INFO     -  [18:16:18] Serving on http://127.0.0.1:8000/
```

#### 进行配置

mkdocs 的配置简单明了，采用 yml 格式：

```
site_name: MkLorum
site_url: https://example.com/
nav:
    - Home: 'index.md'
    - About: 'markdown.md'
theme: readthedocs
```

当文档比较复杂时，可以通过嵌套的方式对 nav 进行配置，例如在 Home 下还有子菜单，menu1 和 menu2：

效果如下：
![](https://assets.guaishow.cn/Picgo/20211122162206.png)

#### 更换主题

下载主题：

```
pip **install** mkdocs-material mkdocs-windmill
```

mkdocs.yml里添加:

```
theme:
  name: 'material'
# 也可以选bootstrap
```

其他的一些配置：

```
theme:
  name: "material"
  # logo: 'images/logo.svg'
  logo:
      icon: "mkdocs"
  palette:
      primary: "black"
      accent: "deep orange"
  language: "zh"
```

material页面风格：
![](https://assets.guaishow.cn/Picgo/20211122162408.png)

#### 更多主题：https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

#### 一些约定

#### 生成站点

执行mkdocs build命令，生成站点，点击index.html即可

```
mkdocs build
```

### 使用sphinx

#### 安装sphinx和主题

```
pip install sphinx sphinx_rtd_theme
```

#### 创建项目

创建一个文件夹后，执行命令

```
sphinx-quickstart
```

#### 编写文档

![](https://assets.guaishow.cn/Picgo/20211122162733.png)

#### 修改主题

在conf.py文件中添加这两行代码，修改主题

```
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'

# 记得删除下面的html_theme = 'alabaster'
```

更多主题请参考：[https://sphinx-themes.org/](https://sphinx-themes.org/)

#### 构建站点

在根目录输入命令，即可生成网站构建。在build/html目录下即可看到生成的网站

```
make html
```

点击index.html即可查看
![](https://assets.guaishow.cn/Picgo/20211122162830.png)

### 使用Teadocs

Teadocs 是一款能够帮你快速构建html文档的工具，它基于nodejs编写，并使用markdown来编写文档内容。

Teadocs 提供内置的搜索技术，除了编写好你引以为豪的内容以外，你无需关注的任何额外的技术问题。

你可以使用它来编写开源书籍、API文档学习、笔记、学习心得、甚至可以用来写博客。

#### 安装

需要nodejs版本 >= 8.0，npm 版本 > 3.

```
$ npm install -g teadocs
```

初始化一个文档项目

```
$ teadcos init mydocs
```

进入这个文档目录

```
$ cd mydocs
```

此步骤是进入文档编辑模式（开发模式），此模式将监视markdown文件的变化，实时热替换html页面。

```
$ teadocs dev
```

#### 自动生成项目初始结构

```
$ teadocs init
```

### 编译成html

```
$ teadocs build
```

#### 文档目录结构介绍

#### 主配置文件说明

菜单的配置文件是你文档根目录下面的 `teadocs.config.js`，它是一个javascript的文件。

主配置文件的所有配置项都不是必填你完全可以什么也不填写，它的代码如下：

```
'use strict';
const path = require('path')

#### 默认配置

#### 菜单配置文件说明

菜单的配置文件是你文档根目录下面的 `tree.md` 文件，它采用了markdown语法来进行书写。

###### 菜单结构

例如，本文档的菜单结构如下：

##### 符号介绍

语法完全使用markdown里的无序列表定义语法，但是要特别注意以下几点：

+ 代表了在生成的html里默认展开这个菜单，需要注意的是，这不是markdown的语法，这是teadocs的规定，+一定要写在文本的前面，而不是[的前面

#### markdown模版

你编写的markdown文件可以使用内置的ejs模版引擎，比如我们可以轻而易举的写个循环，像这样：

效果：

<% [1,2,3,4].forEach(function () { %>

* 欢迎使用Teadocs文档生成工具
  <% }) %>

#### 自定义主题

你可以构建自己的主题文件，只要符合Teadocs的主题规范，具体可以自行参考默认主题。

如何使用自己构建的主题？
在 teadocs.config.js 文件的 theme.dir 配置项中指定你的自定义主题路径就可以了。

#### 部署

##### 上传到github

可以你的文档源文件上传到github上，使用 .gitignore 屏蔽 ./build 目录。

##### 上传到服务器

建议使用nginx等静态服务器软件搭建一个静态服务器进行访问即可。

##### 运行项目结果

```
teadocs dev
```

默认端口号是3210
![](https://assets.guaishow.cn/Picgo/20211122163913.png)

### docsify

### Dumi

https://d.umijs.org/zh-CN

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

Leave a Comment Cancel reply

3D打印机无线内存卡 WIFI-SD卡开源部分

映泰hifi h77s bios 添加nvme驱动

Typecho CommentToMail 非常漂亮渐变色邮件样式

3D打印机无线内存卡 WIFI-SD 使用安装说明

解决群晖Video Station 不支持当前所选音频的文件和添加DS Video 豆瓣刮削器

使用chrome调试CSS

使typecho支持Emoji表情和地图标识

UEFI+GPT引导系统迁移更换硬盘克隆

2019 年 10 月 24 日

2019年11月10日

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify