使用 Mkdocs 快速搭建自己的文档系统

MkDocs 是一款专为项目文档设计的静态网站生成器，它以其高效、简洁和美观的特点受到开发者的青睐。通过使用 Markdown 语言编写的源文件和一个单一的 YAML 配置文件，用户能够轻松地创建并维护文档站点。生成的 HTML 网站不仅加载速度快，而且可以方便地部署到 GitHub Pages 等静态网站托管平台上，使得分享和协作变得简单。

1. 安装 python 虚拟环境

参考 如何使用 Astral UV 管理 Python 虚拟环境？

# 创建python虚拟环境
uv venv mkdocs --python 3.12 --seed

# 激活虚拟环境
source ~/mkdocs/bin/activate

2. 安装 Mkdocs

要安装 MkDocs,请从命令行运行以下命令:

pip install mkdocs

欲了解更多详情,请参阅 安装指南。

3. 创建新项目

入门非常简单。要创建新项目,请运行以下命令 命令行中的命令:

mkdocs new my-project
cd my-project

初始化完成后的简要目录结构如下:

$tree -L 1 my-project

my-project
├── backend
├── docs
├── frontend
├── mkdocs.yml
├── node_modules
├── package.json
└── yarn.lock

有一个名为 mkdocs.yml 的配置文件, 以及一个名为的文件夹 docs 里面包含您的文档源文件(docs 是 的默认值 docs_dir 配置设置）。现在 docs 文件夹仅包含一个名为 index.md 的页面。

4. 本地启动

MkDocs 配备内置开发服务器,可让您预览文档 当你努力的时候。确保您与 mkdocs.yml 配置文件位于同级目录中,然后通过运行启动服务器 mkdocs serve 命令:

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.22 seconds
INFO    -  [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [15:50:43] Serving on http://127.0.0.1:8000/

打开 http://127.0.0.1:8000/ 在你的浏览器中,你会看到默认 显示的主页:

dev-server 还支持自动重新加载,并将重建您的配置文件、文档目录或主题中的任何内容。

5. 更改网站名称

现在尝试编辑配置文件: mkdocs.yml。改变 site_name 设置为 MkLorum 并保存文件。您的浏览器应立即重新加载,您将看到您的新网站名称。

6. 创建您的第一个页面

现在向您的文档添加第二页:

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

由于文档网站将包含一些导航标头, 因此您可能需要编辑配置文件 mkdocs.yml 并添加一些导航菜单:

site_name: MkLorum
nav:
  - Home: index.md
  - About: about.md

7. 设置一个漂亮的主题

mkdocs 内置了一些主题，如果要使用内置的主题只要修改 mkdocs 配置文件的 theme 属性即可。

现在更改配置文件以改变文档主题（theme）。编辑 mkdocs.yml 文件并添加 theme 设置:

site_name: MkLorum
nav:
  - Home: index.md
  - About: about.md
theme: readthedocs

保存您的更改,您将看到正在使用的 ReadTheDocs 主题。

如果要安装第三方主题，则需要先安装依赖，然后再修改主题属性。

pip install mkdocs-material

8. 修改网站的图标

默认情况下,MkDocs 使用 MkDocs favicon 图标。要使用不同的图标,请在 docs 目录目录下创建 一个 img 子目录，并复制您的自定义 favicon.ico 文件到该目录。MkDocs 将自动检测并使用该文件作为您网站图标。

9. 编译

您已准备好部署您的第一遍 MkLorum 文档。首先构建文档:

mkdocs build

这将创建一个新目录,名为 site。看看里面 目录:

$ ls site
about  fonts  index.html  license  search.html
css    img    js          mkdocs   sitemap.xml

请注意，您的源文档已输出为两个 HTML 文件，分别命名为 index.HTML 和 about/index.HTML。作为文档主题的一部分，您还可以将各种其他媒体复制到站点目录中。你甚至有一个 sitemap.xml 文件和 mkdocs/search_index.json。

如果您使用源代码控制,例如 git 你可能不想 检查存储库中的文档版本。添加包含以下内容的一行 site/ 致你 .gitignore 文件。

10. 如何发布 mkdocs 网站

# 配置github网站
git remote add origin git@github.com:example/example.github.io.git

git config user.name exampleuser
git config user.email exampleuser@example.com

git add -A

git commit -m "initial commit"

将 public key 添加到 github 账号：

部署

mkdocs gh-deploy

11. 图片处理

为 MkDocks 增加了对齐图像、向图像添加标题（将其渲染为图形）以及标记大图像以进行延迟加载的能力。添加以下行至 mkdocs.yml:

markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.blocks.caption

对于 pymdownx 需要安装 python 模块 pip install pymdown-extensions

如何使用参考：https://squidfunk.github.io/mkdocs-material/reference/images/

开启代码块语法高亮

参考：https://squidfunk.github.io/mkdocs-material/reference/code-blocks/

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

代码块开启拷贝功能

theme:
  features:
    - content.code.copy

12. 参考文档

深入浅出 MkDocs：打造高效且美观的项目文档

Getting Started with MkDocs

mkdocs-material 官网

Material for MkDocs reference images