在静态站点生成器（SSG）的生态中，Mkdocs 凭借其独特优势脱颖而出。与依赖 Node.js 环境的 Hexo 以及借助 Go 语言编译的 Hugo 不同，Mkdocs 仅需基础的 Python 环境即可运行，对不擅长前端开发的创作者极为友好。相较于 WordPress 这类动态博客，Mkdocs 摒弃了数据库的复杂设置，无需繁琐的后台管理，与以 Markdown 为核心的技术写作场景高度契合。
以我自身的需求为例，博客内容中 80% 为技术笔记，涵盖代码示例与架构图，20% 为日常瞎扯的文章。我期望在创作过程中，实现从本地写作、版本管理到自动部署的高效流程，杜绝任何冗余环节。同时，也希望博客具有良好的扩展性，能轻松转化为项目文档。
Mkdocs 的核心优势体现在多个方面。其架构极为轻量化，整个博客本质上是由 Markdown 文件与配置文件构成，使用 Git 托管时，文件体积通常小于 10MB。它具备强大的文档化基因，原生支持目录树导航与 API 文档生成，在组织技术内容方面，比通用博客工具的效率高出 30%（我猜的）。此外，Material 主题体系搭配丰富的插件，如公式渲染、版本追踪等，让博客在美观与功能上达到完美平衡。
成果预览：
（1）下载Github Desktop
（2）有一个GitHub账号
（3）有一个新建好的GitHub仓库且已经克隆到本地的目标文件夹
打开克隆到本地的目标文件夹下的终端依次执行
# 创建独立虚拟环境（推荐使用 poetry 或 venv）
python -m venv mkdocs-env
source mkdocs-env/bin/activate # Linux/macOS 系统
mkdocs-env\Scripts\activate # Windows 系统
# 安装 Mkdocs
pip install mkdocs #可省略这一步
pip install mkdocs-material在目标文件夹下执行 mkdocs new my-blog 命令，将生成如下项目结构：
my-blog/
├── mkdocs.yml # 核心配置文件，采用 YAML 格式定义站点元数据
└── docs/
└── index.md # 首页其中mkdocs.yml关键配置解读如下：
site_name: "xxx的博客" # 站点名称，显示于导航栏
site_url: "https://your-domain.com" # 部署后的域名
nav: # 导航栏菜单结构，层级与目录结构对应
- 首页: index.md
theme:
name: material #主题启动实时预览服务器：
mkdocs serve # 可自定义端口在浏览器中打开 http://127.0.0.1:8000/，即可实时查看效果。
编写Markdown推荐搭配 VS Code 的「Markdown All in One」插件，该插件具备以下实用功能：
学习markdown请去：https://markdown.com.cn/
# 在 mkdocs.yml 中配置主题
theme:
name: material # 启用 Material 主题
features:
- navigation.tabs # 顶部标签页导航
- navigation.sections # 自动提取标题生成章节锚点
palette:
- scheme: default # 浅色模式
- scheme: slate # 暗黑模式（用户可切换）详细的配置教材请看：https://wcowin.work/blog/Mkdocs/mkdocs2/
进阶定制：通过修改 CSS/JS 实现自定义样式
在 docs/stylesheets/ 目录下创建 extra.css 文件（JS文件同理）：
:root > * {
--md-primary-fg-color: #4c94cb;
--md-primary-fg-color--light:#4c94cb;
--md-primary-fg-color--dark: #4c94cb;
}
button.md-top {
font-family: LXGW WenKai; /* 修改字体 */
font-size: 16px; /* 修改字体大小 */
font-weight: lighter;/* 修改字体粗细 */
color: #518FC1; /* 修改字体颜色 */
}
:root {
--md-text-font: "LXGW WenKai";
} /* 字体 */再在mkdocs.yml中引入custom.css
extra_css:
- stylesheets/extra.css # 自定义CSS
推荐插件清单：
| 插件名称 | 功能场景 | 链接 |
| mkdocs-material-extensions | 支持 Mermaid 图表、Katex 数学公式等功能 | https://pypi.org/project/mkdocs-material-extensions/ |
| mkdocs-git-revision-date-localized | 显示文章最后更新时间 | https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/index.html |
| 令人惊叹的MkDocs项目和插件列表 | https://github.com/mkdocs/catalog#-theming | |
实战：插入 Mermaid 流程图
```mermaid
graph LR
A[需求分析] --> B[原型设计]
B --> C[开发编码]
C --> D[测试验收]
D --> E[部署上线]
```渲染效果：
在 .github/workflows/ 目录下创建 ci.yml 文件：
mkdir .github
cd .github
mkdir workflows
cd workflows
vim ci.yml 
ci.yml里这样写：
name: ci
on:
push:
branches:
- master
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-python@v4
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- uses: actions/cache@v3
with:
key: mkdocs-material-${ env.cache_id }
path: .cache
restore-keys: |
mkdocs-material-
- run: pip install mkdocs-git-revision-date-localized-plugin
- run: pip install mkdocs-git-authors-plugin
- run: pip install mkdocs-git-committers-plugin-2
- run: pip install mkdocs-rss-plugin
# - run: pip install jieba
- run: pip install mkdocs-markdownextradata-plugin
# - run: pip install mkdocs-glightbox
# - run: pip install "mkdocs-material[imaging]"
# - run: pip install mkdocs-statistics-plugin
# - run: pip install mkdocs-rss-plugin
- run: pip install mkdocs-material
- run: pip install --upgrade --force-reinstall mkdocs-material
- run: mkdocs gh-deploy --force配置完成后，每次向 main 分支推送内容，都会自动构建并部署到 GitHub Pages 。
注意去开头新建好的Github仓库setings/Actions/General 勾选这两项
到这里先检查一下你的目录结构
目录树状图:
$ tree -a
myblog/
├── .github
│ ├── .DS_Store
│ └── workflows
│ └── ci.yml
└── docs/
│ ├── index.md # 首页内容，支持 Markdown 及 Mkdocs 扩展语法
│ └── about.md # 示例页面，可根据需求进行增删或修改
└── mkdocs.yml做好上面的检查工作，最后去Github Desktop上传到Github仓库即可。
看看仓库的分支里有无出现gh-pages
出现gh-pages后去仓库的setings/pages选择下图示意的路径
安装 oss2 工具用于上传图片：
# 上传脚本示例（需提前安装 pip install oss2）
import oss2
auth = oss2.Auth('your-access-key', 'your-secret-key')
bucket = oss2.Bucket(auth, 'oss-cn-hangzhou.aliyuncs.com', 'your-bucket-name')
bucket.put_object_from_file('img/post-cover.jpg', 'local-path.jpg')在 Markdown 中引用图片：
---
title: 标题
# 隐藏的模块
hide:
# - navigation # 隐藏左边导航
# - toc #隐藏右边导航
# - footer #隐藏翻页
# - feedback #隐藏反馈
tags:
- 你的标签
---
```git
git init // 初始化本地仓库
git config --global user.name "myname" // 配置用户名
git config --global user.email "myname@mymail.com" //配置邮箱
git remote add origin code@github.git //绑定本地和远程仓库
git pull // 拉取远程仓库的变化来同步本地的状态
git add // 确认本地仓库的变化到本地缓存区
git commit // 确认本地缓存区的内容，可以准备push
git push // 提交本地仓库到远程仓库
git status // 确定本地缓存区的状态
```
//安装mkdocs
pip install mkdocs-material
//更新mkdocs
pip install --upgrade --force-reinstall mkdocs-material
//完成编辑后，您可以使用以下命令从 Markdown 文件构建静态站点：
mkdocs build --clean
//新标签打开
{target=“_blank”}
示例：[Wcowin's web](https://wcowin.work/){target=“_blank”}每次写完文章在mkdocs.yml的nav部分使用相对地址引用即可
| 工具 | 学习成本 | 扩展性 | 适合场景 |
| Mkdocs | ★☆☆☆☆ | ★★★☆☆ | 技术博客、项目文档 |
| Hugo | ★★☆☆☆ | ★★★★☆ | 高性能博客、新闻站点 |
| Docusaurus | ★★★☆☆ | ★★★★★ | 多语言文档、企业官网 |
新人第一次发文，如有冒犯或者错误以及疑问之处，敬请在评论区指出，我会详细阅读后回复
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。