MkDocs 文档站点快速搭建
欢迎来到我的文档
这是使用 MkDocs 构建的第一个站点。
快速开始
请浏览左侧导航查看各章节。
你可以继续在 `docs/` 下创建更多 `.md` 文件，如 `about.md`、`guide/getting-started.md` 等。
### 配置导航结构
编辑 `mkdocs.yml`，定义站点名称和页面导航：
```yaml
site_name: 我的文档
site_description: 使用 MkDocs 构建的技术文档站点
theme: material
nav:
- 首页: index.md
- 关于: about.md
- 使用指南:
- 快速入门: guide/getting-started.md
- 配置详解: guide/configuration.md
保存后，所有在 nav 中定义的页面都会自动生成导航菜单。
实时预览与写作
MkDocs 内建开发服务器，支持内容变更后自动刷新浏览器。
在项目根目录（包含 mkdocs.yml 的目录）运行：
mkdocs serve
打开浏览器访问 http://127.0.0.1:8000，即可看到你的站点。编辑任何 Markdown 文件并保存，浏览器会自动刷新显示最新内容。
若要停止服务器，在终端按下 Ctrl + C。
配置与自定义
更换主题
在 mkdocs.yml 中修改 theme 字段即可切换主题。内置主题有 mkdocs 和 readthedocs。若使用 Material 主题，设置如下：
theme:
name: material
Material 主题支持颜色、字体、语言、特性开关等高级配置，例如：
theme:
name: material
palette:
primary: indigo
accent: pink
language: zh
features:
- navigation.tabs
- search.highlight
启用常用扩展
MkDocs 通过 Python-Markdown 扩展增强写作能力。在 mkdocs.yml 中添加 markdown_extensions：
markdown_extensions:
- admonition
- codehilite:
guess_lang: false
- toc:
permalink: true
- pymdownx.superfences
- pymdownx.details
admonition：可以添加提示框、警告等区块。codehilite：代码语法高亮。toc：自动生成目录，并可添加段落锚点。superfences：支持更复杂的代码块嵌套。details：实现 HTML 折叠块。
添加插件
MkDocs 支持插件系统。例如，安装并启用搜索插件、RSS 插件等。在 mkdocs.yml 中配置 plugins：
plugins:
- search
- minify:
minify_html: true
插件需提前安装，search 已内置无需额外安装。
构建静态文件
站点开发完成后，执行构建命令生成纯静态 HTML、CSS、JS 文件：
mkdocs build
构建结果默认输出到 site/ 目录。你可以将该目录部署到任何静态文件托管服务，如 GitHub Pages、Netlify、Vercel 等。
注意：构建前确保没有错误链接，可以在开发服务器中检查所有页面。
部署到 GitHub Pages
MkDocs 提供了便捷的部署命令，将 site/ 目录推送到 GitHub 仓库的 gh-pages 分支。
前提条件
- 已创建 GitHub 仓库，并关联本地仓库。
- 所有修改已提交到远程
main分支。
一键部署
在项目根目录执行：
mkdocs gh-deploy
MkDocs 会自动构建站点，并将构建后的文件推送到远程 gh-pages 分支。几分钟后，你的站点即可通过 https://<用户名>.github.io/<仓库名> 访问。
你可以在 mkdocs.yml 中指定自定义域名等 GitHub Pages 配置，或通过 CNAME 文件实现。
常见问题与技巧
如何让链接在新标签页打开？
在 Markdown 中无法直接控制，但可以通过 MkDocs-Material 主题的配置实现打开外部链接为新窗口，在 mkdocs.yml 中设置：
theme:
name: material
features:
- navigation.tabs
extra:
consent:
actions:
- accept
或通过自定义 JavaScript 实现。
如何处理图片和附件？
将图片或其他资源文件放在 docs/ 下的某个子目录，例如 docs/assets/images/，然后在 Markdown 中使用相对路径引用：
构建时会自动复制这些文件。
如何使用相对链接？
MkDocs 会自动将 .md 文件扩展名转换为 .html，所以页面间的链接只需使用 .md 扩展名即可：
请参考 [配置详解](guide/configuration.md)