告别Word写文档！用MkDocs一键生成专业文档站

前言

在信息爆炸的时代，一份清晰、结构化且易于维护的技术文档，早已成为项目成败的关键。然而，用 Word 或传统富文本工具编写文档，往往意味着格式混乱、版本失控、协作困难，更别提响应式阅读和多端适配了。是时候告别“.docx”时代了！

MkDocs——这款基于 Markdown 的静态文档生成器，正以极简的配置、优雅的主题（如 Material for MkDocs）和一键部署的能力，重新定义专业文档的创作方式。你只需专注内容本身，用纯文本书写逻辑清晰的说明，MkDocs 就能自动为你生成一个美观、搜索友好、支持 Git 协作的现代化文档网站。

本文将带你从零开始，快速搭建属于你的专属文档站，真正实现：写得轻松，看得舒服，管得高效。

image-20260716161022836

1.什么是MkDocs？

MkDocs是一个快速、简单、静态的文档生成工具，专为项目文档而设计。它使用Markdown（一种轻量级标记语言）来编写内容，并通过一条命令将这些Markdown文件自动转换成一个结构清晰、美观且响应式的静态网站。

核心特点

特性 说明
基于 Markdown 写文档就像写笔记一样简单，无需学习复杂排版，专注内容本身。
纯静态网站 生成的是 HTML/CSS/JS 文件，可部署到任何 Web 服务器、GitHub Pages、GitLab Pages、Vercel、Netlify 等平台，免费又高效。
主题丰富 官方支持 Material for MkDocs 等现代化主题，支持暗色模式、搜索、导航侧边栏、代码高亮等专业功能。
版本友好 文档即代码（Docs as Code），天然适配 Git，便于团队协作、版本控制和 CI/CD 自动发布。
配置简单 只需一个 mkdocs.yml 配置文件，定义站点标题、导航结构、插件等，5 分钟即可上手。

基本工作流程

  • 用 Markdown 写 .md 文件（如 index.md, getting-started.md）
  • 编写 mkdocs.yml 配置站点结构
  • 运行 mkdocs serve 本地预览
  • 运行 mkdocs build 生成静态网站
  • 将 site/ 目录部署到任意托管平台

适用场景

  • 开源项目技术文档（如 FastAPI、Requests 等知名项目都在用）
  • 公司内部知识库或 API 手册
  • 个人博客或笔记网站
  • 教程、说明书、用户指南等结构化内容

MkDocs = Markdown + 极简配置 + 专业文档网站，让你像写代码一样写文档，像部署应用一样发布知识。

如果你厌倦了Word的格式混乱和PDF的更新噩梦，MkDocs正是现代开发者和团队构建高质量文档的理想选择。

2.安装前提条件

Python环境

  • 版本要求：Python 3.8 或更高版本
  •  注意：MkDocs 从 v1.5.0 起已不再支持 Python 3.7 及以下版本。

验证命令

python3 --version

pip（Python 包管理器）

  • 用于安装 MkDocs 及其插件。
  • 通常随 Python 3 一起安装，但某些精简系统（如 Alpine、最小化 CentOS）可能需要手动安装。

验证命令

pip3 --version

网络访问能力（可选但推荐）

  • 安装时需连接 PyPI 下载包。
  • 若在内网或受限环境，需配置：
    • DNS 正确解析（如 pypi.org）
    • 或使用国内镜像源（如清华、阿里云）：
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple/ mkdocs

文件系统写权限

  • MkDocs 需要能在项目目录中创建/修改文件（如 docs/、site/ 目录）。
  • 确保当前用户对工作目录有读写权限。

最低可行配置

组件 要求
操作系统 Linux / macOS / Windows
Python ≥ 3.8（推荐 3.9+）
pip 已安装
网络 可访问 PyPI（或配置镜像）
权限 当前用户可读写项目目录

检查清单（一键验证）

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

3.安装MkDocs

安装MkDocs文档生成器的命令：

pip install mkdocs

image-20260715162539363

查看mkdocs是否安装成功，执行如下命令：

mkdocs --version

image-20260715162645087

使用Python 3解释器运行MkDocs模块，并输出其版本信息：

python3 -m mkdocs --version

image-20260715164746815

4.启动MkDocs页面

创建一个站点：

mkdocs new dir_name
  • 在创建的目录下，有一个子目录docs，其中包含了源文件、页面等数据；
  • 在创建的目录下，有一个文件mkdocs.yml，这就是配置文件；

image-20260715163420111

正常启动MkDocs默认只监听127.0.0.1，拒绝外部连接。

正确做法是：

mkdocs serve --dev-addr=0.0.0.0:8000

image-20260715163714783

部署完成后，在浏览器中输入 http://IP:8000 就能看到MkDocs的界面：

image-20260715163857271

5.使用MkDocs

5.1 修改站点信息

在站点运行中，我们可以修改mkdocs.yml文件中的站点名site_name：

site_name: 我的第一个站点

image-20260716113741957

回到页面可以看到，站点名已经更新完成：

image-20260716113634311

5.2 添加页面

在部署过程中，mkdocs已经为我们创建了一个页面，进入/dir_name/docs可以看见index.md文件，就是他们自然生成的：

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

image-20260716150750797

在该目录下(/dir_name/docs)，创建页面，比如：my.md

  • 文档格式为markdown格式
vi my.md

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

image-20260716150951233

刷新就可以在MkDocs中看见啦！

image-20260716145803094

image-20260716145814483

这样我们就成功的创建了一个页面！

5.3 添加多级页面

我们可以添加多级页面。首先，在 docs 目录下新建一个子目录，此处命名为 app；然后在该目录中创建多个文档文件，例如 C.md、Java.md 和 Python.md。最终的目录结构如下：

image-20260716154734495

然后回配置文件中修改配置项：

vi mkdocs.yml

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

image-20260716154920055

刷新，回到页面：

image-20260716155009224

二级页面就做好啦，除了二级页面还可以做三级页面：

# 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

image-20260716155418749

刷新页面，显示成功！

image-20260716155307191

5.4 跳转页面

除了在导航栏上设置页面，我们也可以在页面上通过markdown语法进行跳转：

举例，在my.md中要跳转到java.md页面：

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

image-20260716155756989

刷新页面就会显示出来：

image-20260716155848372

image-20260716155957651

5.5 更改主题

mkdocs默认有两个主题：mkdocs和readthedoc，默认使用mkdocs。

我们在配置文件中修改，使用readthedocs主题：

theme:
  name: readthedocs

image-20260716160924023

刷新页面后主题更换成功！

image-20260716160424342

MkDocs用于快速构建静态文档站点，而通过与cpolar结合，可轻松将本地MkDocs服务安全、稳定地暴露到公网，无需复杂配置或部署服务器。cpolar凭借其内网穿透能力，让开发者在本地编写和预览文档的同时，即可实时分享可访问的公网链接，极大提升了协作与演示效率——真正实现“写完即分享”。

5.安装cpolar实现随时随地开发

5.1 什么是cpolar？

cpolar是一款安全高效的内网穿透工具，无需公网IP或复杂配置，只需一条命令，即可将本地服务器、Web服务或任意端口映射到公网，让你随时随地远程访问内网应用，特别适合开发调试、远程运维和应急部署等场景。

5.2 部署cpolar

cpolar 可以将你本地电脑中的服务（如 SSH、Web、数据库）映射到公网。即使你在家里或外出时，也可以通过公网地址连接回本地运行的开发环境。

❤️以下是安装cpolar步骤：

官网在此：https://www.cpolar.com

使用一键脚本安装命令：

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

image-20250725104019896

安装完成后，执行下方命令查看cpolar服务状态：（如图所示即为正常启动）

sudo systemctl status cpolar

22e5adfaf290a17fc3384bb296055259

Cpolar安装和成功启动服务后，在浏览器上输入虚拟机主机IP加9200端口即:【http://ip:9200】访问Cpolar管理界面，使用Cpolar官网注册的账号登录,登录后即可看到cpolar web 配置界面,接下来在web 界面配置即可：

打开浏览器访问本地9200端口，使用cpolar账户密码登录即可,登录后即可对隧道进行管理。

8a6698b1bf26d64ba3645827fbfb1c29

6.配置公网地址

登录cpolar web UI管理界面后,点击左侧仪表盘的隧道管理——创建隧道：

  • 隧道名称：可自定义，本例使用了:mkdocs，注意不要与已有的隧道名称重复
  • 协议：http
  • 本地地址：8000
  • 域名类型：随机域名
  • 地区：选择China Top

image-20260716164238962

创建成功后，打开左侧在线隧道列表,可以看到刚刚通过创建隧道生成了公网地址，接下来就可以在其他电脑或者移动端设备（异地）上，使用地址访问。

image-20260716165239006

访问成功。

7.保留固定公网地址

使用cpolar为其配置二级子域名（cpolar官网-安全的内网穿透工具 | 无需公网ip | 远程访问 | 搭建网站），该地址为固定地址，不会随机变化。

image-20250918151358733

点击左侧的预留，选择保留二级子域名，地区选择china Top，然后设置一个二级子域名名称，我使用的是mkdocs，大家可以自定义。填写备注信息，点击保留。

image-20260716165331716

登录cpolar web UI管理界面，点击左侧仪表盘的隧道管理——隧道列表，找到所要配置的隧道，点击右侧的编辑。

image-20260716165355090

修改隧道信息，将保留成功的二级子域名配置到隧道中

  • 域名类型：选择二级子域名
  • Sub Domain：填写保留成功的二级子域名
  • 地区: China Top

点击更新

image-20260716165427305

更新完成后，打开在线隧道列表，此时可以看到随机的公网地址已经发生变化，地址名称也变成了保留和固定的二级子域名名称。

image-20260716165448047

最后，我们使用固定的公网地址在任意设备的浏览器中访问，可以看到成功访问的页面，这样一个永久不会变化的二级子域名公网网址即设置好了。

image-20260716165501546

总结

本文详细的介绍了如何使用MkDocs替代传统 Word文档，通过Markdown编写内容，一键生成结构清晰、样式美观、支持多级导航的专业静态文档网站；配合cpolar内网穿透工具，还能快速将本地文档站分享至公网，实现高效协作与即时预览，彻底告别格式混乱、版本难控的Word时代。

感谢您对本篇文章的喜爱，有任何问题欢迎留言交流。cpolar官网-安全的内网穿透工具 | 无需公网ip | 远程访问 | 搭建网站

Share:

鸽子

鸽子

我是鸽子，是这个网站的文章编辑之一！喜欢研究各种有趣的开源项目。希望大家喜欢我的文章！

发表回复

目录

On Key

推荐文章