为技术项目量身定做的文档工具MkDocs

发表于 更新于 分类于 Waline： 阅读次数： 本文字数： 2.2k 阅读时长 ≈ 2 分钟
MkDocs 是一个静态网站生成器，专门用于创建项目文档。

什么是 MkDocs ？

MkDocs 是一款快速、简单且极其出色的静态网站生成器，专门用于构建项目文档。文档源文件以 Markdown 编写，并使用单个 YAML 配置文件进行配置。它易于使用，并且可以使用第三方主题、插件和 Markdown 扩展进行扩展。

软件的主要特点：

  1. Markdown 支持：MkDocs 支持标准的 Markdown 语法，使得编写文档变得简单快捷。
  2. 主题丰富：MkDocs 提供了多种预设主题，用户可以选择一个主题来定制文档的外观和感觉。
  3. 导航栏：MkDocs 可以自动生成一个导航栏，方便用户在不同页面间导航。
  4. 版本控制：MkDocs 支持文档的版本控制，可以为不同版本的项目维护不同的文档集。
  5. 插件系统：MkDocs 拥有一个插件系统，允许用户扩展其功能，例如添加自定义的导航栏、搜索功能等。
  6. 国际化：MkDocs 支持多语言文档，可以为不同语言的用户提供本地化的文档。
  7. 部署简单：生成的文档是静态 HTML 文件，可以部署在任何静态文件服务器上，包括 GitHub Pages。
  8. 实时预览：MkDocs 提供了一个开发服务器，可以在编写文档时提供实时预览，方便查看文档效果。
  9. 配置灵活：MkDocs 的配置文件（通常是 mkdocs.yml）允许用户定制网站的各种设置，如标题、描述、URL 等。
  10. 社区支持：作为一个流行的开源项目，MkDocs 拥有一个活跃的社区，提供帮助和支持。
  11. 易于使用：MkDocs 的安装和使用都非常简单，通过 Python 的包管理器 pip 即可安装。
  12. 扩展性：用户可以通过编写自定义脚本或使用社区提供的扩展来进一步定制 MkDocs 的行为。

什么是 Material for MkDocs ?

Material for MkDocs 是基于 MkDocs 的强大文档框架。支持 docker 部署方式。

新建文档

在群晖上以 Docker 方式运行。

首先要在指定的目录中，创建项目文档及配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 新建文件夹 mkdocs 和 子目录
mkdir -p /volume1/docker/mkdocs/docs

# 进入 mkdocs 目录
cd /volume1/docker/mkdocs

# 新建站点
docker run -it \
   --rm \
   -v $(pwd)/:/docs \
   squidfunk/mkdocs-material new .
```   

注意最后的那个点别漏了

![](https://cdn.jsdelivr.net/gh/wbsu2003/images2024@main/picgo/2024/05/202406292127967.png)

这将创建以下结构

```bash
.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

根目录下会生成 mkdocs.yml

docs 目录中会生成 index.md

新建的 mkdocs.yml 只有一行

1
site_name: My Docs

我们可以根据需要进行修改，例如下面👇这样

1
2
3
4
5
6
7
8
9
10
11
12
site_name: My Docs
site_url: https://laosu.tech/
site_description: Markdown 写的项目文档。
site_author: laosu

nav:
    - Home: index.md

plugins:
    - search

theme: material

因为包含了了中文，所以记得采用 UTF-8 格式保存

实时预览

MkDocs 包含一个实时预览服务器，因此您可以在编写文档时预览更改。

1
2
3
4
5
6
# 边写边预览
docker run -it \
   --rm \
   -p 5065:8000 \
   -v $(pwd)/:/docs \
   squidfunk/mkdocs-material

在浏览器中输入 http://群晖IP:5065 就能看到主界面

你在 index.md 上做的任何修改，不需要刷新页面，会显示出来

接下来我们要做的是研究 MkDocs 的高级配置，https://squidfunk.github.io/mkdocs-material/creating-your-site/#advanced-configuration，来研究如何改颜色、改字体、设置版本控制等

生成站点

完成编辑后，你可以使用以下命令从 Markdown 文件构建静态站点

1
2
3
4
docker run -it \
   --rm \
   -v $(pwd)/:/docs \
   squidfunk/mkdocs-material build

会在根目录生成 site 子目录

此目录的内容构成了您的项目文档。无需操作数据库或服务器，因为它是完全独立的。该网站可以托管在 GitHub Pages、GitLab Pages、您选择的 CDN 或您的私人网络空间上

参考文档

mkdocs/mkdocs: Project documentation with Markdown.
地址：https://github.com/mkdocs/mkdocs

MkDocs
地址：https://www.mkdocs.org/

squidfunk/mkdocs-material - Docker Image | Docker Hub
地址：https://registry.hub.docker.com/r/squidfunk/mkdocs-material/

Creating your site - Material for MkDocs
地址：https://squidfunk.github.io/mkdocs-material/creating-your-site/