
## 一 背景

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 映像捆绑在一起：

*   [mkdocs-minify-plugin](https://github.com/byrnereese/mkdocs-minify-plugin)
*   [mkdocs-redirects](https://github.com/datarobot/mkdocs-redirects)

### 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
```

更多配置参考：<https://squidfunk.github.io/mkdocs-material/creating-your-site/#advanced-configuration>

也可以查看插件：<https://squidfunk.github.io/mkdocs-material/setup/extensions/>

#### 3.2.3 预览站点

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

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

通过浏览器[localhost:8000](http://localhost:8000/) 进行访问

![](https://developer.qcloudimg.com/http-save/yehe-1137075/deb59acf0c4910c4bf5adc5dfb65d7c6.png#?w=1552\&h=784\&s=319508\&e=png\&a=1\&b=fbfbfb)

#### 3.2.4 构建站点

使用build参考可以进行构建，之后可以发布到 [GitHub Pages](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#github-pages), [GitLab Pages](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#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](https://github.com/features/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

```

![](https://developer.qcloudimg.com/http-save/yehe-1137075/60d32b1f3389df8531476b82fa27a78c.png#?w=2934\&h=1580\&s=322962\&e=png\&a=1\&b=ffffff)

![](https://developer.qcloudimg.com/http-save/yehe-1137075/ebafbef9bfa2b03b675feac2ac5293b0.png#?w=2776\&h=1550\&s=450459\&e=png\&a=1\&b=fefefe)

*   自定义域名

## 五 高级配置

### 5.1 Google Analytics

登陆[Google Analytics](https://analytics.google.com/analytics/web/provision/?utm_source=marketingplatform.google.com\&utm_medium=et\&utm_campaign=marketingplatform.google.com/about/analytics/#/provision)

![](https://developer.qcloudimg.com/http-save/yehe-1137075/daa11a449c34445d522ce108da9adf25.png#?w=2956\&h=1564\&s=513776\&e=png\&a=1\&b=fefefe)

### 5.2 配置敏感信息secret

![](https://developer.qcloudimg.com/http-save/yehe-1137075/28abecf1c0728c12139de9985fc4c53b.png#?w=1528\&h=948\&s=370398\&e=png\&a=1\&b=fdfdfd)



![](https://developer.qcloudimg.com/http-save/yehe-1137075/5ad2200d893ffb1434b028a8d70edf88.png#?w=2392\&h=1180\&s=394597\&e=png\&a=1\&b=1a1a1a)

![](https://developer.qcloudimg.com/http-save/yehe-1137075/68d550c3f7dd3b940a88156371f20689.png#?w=2310\&h=1264\&s=448444\&e=png\&a=1\&b=1a1a1a)

## 六 总结

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

## 参考链接

*   <https://www.mkdocs.org/>
*   <https://analytics.google.com/analytics/web/provision/?utm_source=marketingplatform.google.com&utm_medium=et&utm_campaign=marketingplatform.google.com/about/analytics/#/provision>


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

使用 Material for MkDocs 构建个人博客

Devops工程师

开发工具

前端

响应式设计

TypeScript

服务器

容器

Docker

GitHub

11.11畅享AI算力 云启新增长

4核4G3M云服务器 新用户低至38元/年！

域名特惠新用户低至1元！


domain

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

使用 Material for MkDocs 构建个人博客-腾讯云开发者社区-腾讯云

使用 Material for MkDocs 构建个人博客

使用 Material for MkDocs 构建个人博客

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐