使用 Material for MkDocs 构建个人博客

一 背景

Material for MkDocs 是一个功能强大且美观的主题，非常适合用来构建在线博客。它提供了许多开箱即用的功能，可以让你轻松创建专业的博客网站。

二 特性

• 这只是 Markdown ... — 用 Markdown 编写您的技术文档——无需了解 HTML、JavaScript 或 CSS。 MkDocs 的材料将完成繁重的工作并创建一个美观且实用的网站。

• 但还有更多——与 Python Markdown Extensions 原生集成，添加标注、选项卡式内容容器、数学公式、评论标记、任务列表以及 10k 多个图标和表情符号。

• 响应式设计——从头开始构建，适用于各种设备——从手机到宽屏。底层的流体布局将始终完美地适应可用的屏幕空间。

• 静态，但可搜索——几乎神奇的是，您的技术文档网站将可以轻松搜索。 MkDocs 的材料带有内置搜索 - 无需服务器。

• 许多配置选项——更改调色板、字体系列、语言、图标、网站图标和徽标。添加源存储库链接、指向您的社交资料的链接和 Google Analytics - 所有这些都只需几行配置。

• 真正的国际化——感谢许多贡献者，Material for MkDocs 包括 40 多种语言的翻译，并提供完整的原生 RTL（从右到左）支持。

• 可访问性——MkDocs 的材料提供可扩展的键盘导航和语义标记，包括角色属性和地标。此外，布局尊重用户的默认字体大小。

• 现代架构——MkDocs 底层代码库的 Material 构建在 TypeScript、RxJS 和 SCSS 之上，为主题扩展和定制带来了极好的可能性。

MkDocs 的素材遵循的是赞助商/软件发布策略，这意味着新功能首先作为内部人员的一部分发布给赞助商。请继续阅读以了解赞助商的成就，如何成为赞助商以获得内部人士的认可，以及这对你有什么好处！

三 安装

3.1 使用docker

docker pull squidfunk/mkdocs-material

mkdocs 可执行文件作为入口点提供，serve 是默认命令。如果您不熟悉 Docker，请不要担心，我们将在以下部分中介绍您。 以下插件与 Docker 映像捆绑在一起：

• mkdocs-minify-plugin
• mkdocs-redirects

3.2 创建站点

3.2.1 创建项目

# 创建项目目录
$ mkdir -p project && cd project
$ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
$ tree
.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

3.2.2 配置站点

最小化配置，在mkdocs.yml文件中添加以下内容。

theme:
  name: material

更多配置参考：squidfunk.github.io/mkdocs-mate…

也可以查看插件：squidfunk.github.io/mkdocs-mate…

3.2.3 预览站点

MkDocs 包含一个实时预览服务器，因此您可以在编写文档时预览您的更改。服务器将在保存后自动重建站点。从以下开始：

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

通过浏览器localhost:8000 进行访问

3.2.4 构建站点

使用build参考可以进行构建，之后可以发布到 GitHub Pages, GitLab Pages站点等。

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material build

INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /docs/site
INFO     -  Documentation built in 1.81 seconds

四 发布站点到Github Pages

在 git 存储库中托管项目文档的好处是能够在推送新更改时自动部署它。 MkDocs 使这变得非常简单。

如果您已经在 GitHub 上托管您的代码，那么 GitHub Pages 无疑是发布项目文档的最便捷方式。它是免费的，而且很容易设置。

4.1 使用GitHub Actions

使用 GitHub Actions，您可以自动部署项目文档。在存储库的根目录中，创建一个新的 GitHub Actions 工作流程，例如.github/workflows/ci.yml，复制粘贴以下内容：

mkdir -p .github/workflows/ && cd .github/workflows/
touch ci.yml

# 内容如下
name: ci 
on:
  push:
    branches:
      - master 
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

• 自定义域名

五 高级配置

5.1 Google Analytics

登陆Google Analytics

5.2 配置敏感信息secret

六 总结

Material for MkDocs 是构建美观且功能强大的在线博客的绝佳选择。它提供简洁直观的界面，丰富的自定义选项和强大的插件支持，让您可以轻松创建个性化的博客平台。通过简单的配置和 Markdown 语法，即可创建专业级的博客内容，并将其发布到 GitHub Pages 等平台。

参考链接

• www.mkdocs.org/
• analytics.google.com/analytics/w…