从Markdown到多级文档站:MkDocs安装、导航配置与远程预览实战

从Markdown到多级文档站：MkDocs安装、导航配置与远程预览实战

前言

MkDocs 的核心并不是"把 Markdown 变漂亮"，而是把文档内容、导航结构和站点展示拆开管理。Markdown 负责正文，mkdocs.yml 负责站点和导航，MkDocs再把这些内容组织成一个可以在浏览器里阅读的文档网站。

这篇从 Python、pip 和 MkDocs 安装开始，创建 dir_name 项目，使用 8000 端口启动开发预览，再逐步完成站点名、Markdown页面、二级和三级导航、页面链接以及 readthedocs 主题切换。

后半部分继续把开发预览页面提供给外部设备访问，并配置固定地址，方便在不同地点查看和演示。

全文重点放在"Markdown内容---MkDocs配置---多级导航---本地预览---远程预览"这条链上，同时把 Python 版本、内置主题和开发服务器的边界说清楚。

相比把所有内容堆在一个大文件里，这种结构更适合持续维护：页面可以拆分，导航可以单独调整，内容修改也更容易配合Git做版本记录。对于项目说明、内部知识库和教程这类会不断增长的资料，后期维护压力会小很多。这也是为什么这篇会把页面组织和导航配置放在比较靠前的位置：真正决定文档站后期好不好维护的，不只是主题好不好看，而是目录、页面和配置之间的关系有没有从一开始就理顺。

1 MkDocs真正适合解决什么问题

如果只是写一份一次性交付的报告，Word仍然很合适。

MkDocs更擅长的是：

项目文档；
API说明；
开发手册；
内部知识库；
教程；
长期持续更新的技术资料。

它的核心思路是：

正文写Markdown，结构写配置，最终输出网站。

这和传统"在一个文档文件里同时处理内容、目录、样式"的方式不太一样。

2 MkDocs不是Word替代品，而是Docs as Code工具

MkDocs生成的是静态文档站。

常见流程是：

Markdown写内容；
mkdocs.yml定义导航；
mkdocs serve用于预览；
mkdocs build生成静态站点文件；
再把生成目录部署到Web服务器或静态托管平台。

所以更准确的说法不是：

Word以后都不用了。

而是：

需要版本管理和长期维护的技术文档，可以考虑改成Markdown + MkDocs。

3 Python版本要求按当前稳定版来看仍是3.8+

先检查Python：

shell 复制代码

python3 --version

再检查pip：

shell 复制代码

pip3 --version

当前MkDocs稳定版包元数据显示：

Python >= 3.8

这一点和教程里的要求一致。

不过以后如果MkDocs主版本升级，Python最低版本也可能调整，长期文章更适合提醒读者以当时的官方安装说明为准。

4 网络受限时可以换PyPI镜像

示例：

shell 复制代码

pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple/ mkdocs

如果默认PyPI速度慢，可以临时切换镜像源。

但镜像同步存在时间差。

如果安装某个刚发布的新版本失败，也要考虑镜像是否还没同步。

5 安装前先做一次环境检查

教程给出的检查方式：

shell 复制代码

python3 --version          # 应 ≥ 3.8
pip3 --version             # 应正常输出
git --version              # （可选）建议安装

这里：

Python和pip是必需的；
Git对MkDocs核心功能不是必需，但做版本管理时很有用；
工作目录需要有写权限。

准备好这些以后再安装MkDocs。

6 安装MkDocs

执行：

shell 复制代码

pip install mkdocs

安装完成后：

shell 复制代码

mkdocs --version

如果系统里有多个Python环境，也可以：

shell 复制代码

python3 -m mkdocs --version

这两种方式主要用于确认MkDocs到底装在了哪个Python环境里。

7 创建第一个MkDocs项目

执行：

shell 复制代码

mkdocs new dir_name

创建以后：

项目里最重要的两个位置是：

docs/
mkdocs.yml

docs/ 放 Markdown 内容。

mkdocs.yml 管理站点配置。

8 启动8000开发预览

教程使用：

shell 复制代码

mkdocs serve --dev-addr=0.0.0.0:8000

然后浏览器访问：

http://IP:8000

这里一定要区分：

这不是正式部署命令。

MkDocs官方把 mkdocs serve 明确定义成：

内置开发服务器。

--dev-addr=0.0.0.0:8000 只是让它监听所有网卡，方便局域网或后续远程预览。

9 为什么不建议把mkdocs serve当生产服务器

开发预览服务器的目标是：

自动重载；
修改后立即看到效果；
写文档时快速预览。

真正要正式发布时，更合理的流程是：

构建静态文件，再交给专门的Web服务器或静态托管平台。

MkDocs官方文档也把 build / gh-deploy 和 serve 分开定义。

所以本文后面的公网部分更准确的定位是：

远程预览 / 临时演示。

而不是完整生产部署。

10 修改站点名称

打开 mkdocs.yml：

shell 复制代码

site_name: 我的第一个站点

回到页面：

可以看到标题已经变化。

这就是MkDocs配置文件最基础的作用：

内容不用动，站点级信息在配置里改。

11 docs目录就是内容入口

进入：

/dir_name/docs

查看：

shell 复制代码

# pwd
/dir_name/docs
# ls
index.md  my.md

这里已经有：

index.md

后面新建的页面也继续放在 docs 目录或其子目录中。

12 新建一个Markdown页面

示例：

shell 复制代码

vi my.md

# 我
## 我叫什么
好好
## 我的性别
女
## 我的身份
打工人
## 我来自哪里
辽宁

刷新以后：

可以看到新页面已经被MkDocs识别。

这一步真正说明：

Markdown文件就是文档内容文件。

以后修改内容，不需要碰HTML。

13 多级文档真正靠目录和nav组织

先在 docs 下创建子目录：

app

再放入：

c.md
java.md
python.md

目录效果：

然后配置：

shell 复制代码

vi mkdocs.yml

site_name: "我的个人文档"
nav:
  - 主页: index.md
  - 我: my.md
  - 我的教程:
    - C: app/c.md
    - Java: app/java.md
    - Python: app/python.md

刷新：

现在导航已经从"几个页面"变成一个有结构的文档站。

14 三级导航继续往下嵌套

示例：

shell 复制代码

# cat mkdocs.yml
site_name: "我的个人文档"
nav:
  - 主页: index.md
  - 我: my.md
  - 我的教程:
    - C: app/c.md
    - Java: app/java.md
    - Python: app/python.md
    - Linux:
      - app/linux/1.md
      - app/linux/2.md

刷新：

三级导航可以继续扩展复杂的教程、产品手册和知识树。

但层级也不是越深越好。

目录太深以后，用户反而不好找内容。

一般更重要的是：

分类稳定；
页面名称清楚；
导航层次可预测。

15 Markdown页面之间可以直接做相对链接

示例：

shell 复制代码

# 添加这行
[去Java.md页面](./app/java.md)

页面效果：

相对链接的好处是：

项目整体移动或换部署地址以后，内部页面关系仍然更容易保持。

16 主题不要把"官方"和"第三方"混在一起

MkDocs当前官方文档明确列出的内置主题有两个：

mkdocs
readthedocs

教程切换的是：

shell 复制代码

theme:
  name: readthedocs

刷新：

所以这一部分可以明确写：

readthedocs是MkDocs内置主题。

Material for MkDocs则属于非常流行的第三方主题，不应写成MkDocs"官方内置主题"。

17 到这里，本地文档站已经能正常使用

已经完成：

MkDocs安装；
新建站点；
8000开发预览；
站点名称；
Markdown页面；
二级导航；
三级导航；
页面跳转；
主题切换。

如果只是本机写文档，到这里已经够用了。

后面的网络入口解决的是：

怎样让其他设备也看到这个开发预览页面。

18 什么时候适合做远程预览

比较适合：

临时给同事看；
演示文档结构；
异地自己预览；
手机检查排版；
发布前确认。

如果要长期正式对外提供文档站，更推荐：

先build，再正式托管。

这两种用途不要混在一起。

19 安装cpolar

执行：

shell 复制代码

sudo curl https://get.cpolar.sh | sh

检查服务：

shell 复制代码

sudo systemctl status cpolar

然后进入：

主机IP:9200

后面的隧道都在这里配置。

20 给8000开发预览创建公网入口

参数：

隧道名称：mkdocs
协议：http
本地地址：8000
域名类型：随机域名
地区：China Top

创建以后查看：

然后从外部浏览器访问：

页面能正常打开以后，说明：

外部浏览器 → 公网地址 → cpolar → MkDocs开发服务器8000

网络链已经通了。

21 这一步证明的是远程预览，不是生产发布

这里很容易写过头。

页面能从公网打开，只能证明：

8000服务在监听；
公网入口正常；
浏览器能够访问。

它不代表：

已经做了正式静态部署；
已经有生产级Web服务器；
已经有完整发布流程；
已经配置缓存、CDN或访问权限。

所以文章里"写完即分享"可以保留在临时演示层面。

22 随机地址适合短时间分享

如果只是临时给别人看：

当前文档结构；
页面效果；
新主题；
导航层级；

随机地址已经足够。

没有必要一开始就做固定入口。

23 需要长期记住地址时再配置固定二级子域名

进入预留页面：

保留名称：

mkdocs

进入隧道列表：

修改为：

二级子域名

更新后：

最后测试：

固定入口可以减少地址变化带来的重复修改。

24 "固定地址"也不要写成永久承诺

源材料里写：

永久不会变化。

更稳妥的是：

在账号、套餐和对应服务条件持续有效的情况下，固定二级子域名不需要像随机地址那样频繁修改。

固定地址解决的是：

好记；
书签稳定；
演示链接少变。

它不等于MkDocs开发服务器自动变成正式生产站。

25 真正正式发布MkDocs，思路应该换一下

如果文档已经写稳定，不再只是预览：

应该从：

mkdocs serve开发服务器

切换到：

构建静态文件 → 部署静态站点

MkDocs官方支持把构建结果部署到：

GitHub Pages；
Read the Docs；
任意能托管静态文件的Web服务器。

所以这篇最适合定位成：

从0搭建MkDocs文档站，并跑通远程预览。

而不是完整生产发布方案。

26 整条链路回头看

内容：

Markdown → docs目录

结构：

mkdocs.yml → nav

本地预览：

mkdocs serve → 8000

远程预览：

外部浏览器 → 公网地址 → 8000

真正完成的是：

Python / pip检查；
MkDocs安装；
项目创建；
页面；
多级导航；
Markdown链接；
readthedocs主题；
8000本地预览；
随机公网预览；
固定地址预览。

需要特别区分：

Word和MkDocs适用场景不同；
Material不是MkDocs内置主题；
mkdocs serve是开发服务器；
公网可达不等于正式部署；
固定地址不等于永久承诺。

总结

整套流程可以拆成四层：Markdown负责内容，mkdocs.yml负责导航和主题，MkDocs负责生成站点，公网入口负责让外部设备访问开发预览页面。

本文已经完成MkDocs安装、单页与多级页面、站内跳转、readthedocs主题，以及随机和固定地址访问。

需要特别注意的是，当前官方稳定版仍支持Python 3.8+，readthedocs是内置主题，而mkdocs serve明确属于开发服务器。

把这些边界说明白以后，这篇更准确的定位不是"彻底告别Word"，而是：把持续更新的技术文档从单个文件，整理成可维护、可导航、可预览的网站结构。