使用 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

shell 复制代码

docker pull squidfunk/mkdocs-material

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

3.2 创建站点

3.2.1 创建项目

shell 复制代码

# 创建项目目录
$ 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文件中添加以下内容。

shelll 复制代码

theme:
  name: material

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

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

3.2.3 预览站点

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

shell 复制代码

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

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

3.2.4 构建站点

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

bash 复制代码

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，复制粘贴以下内容：

shell 复制代码

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