快来美化你的mkdocs吧

Python研究所

发布于 2022-06-17 08:13:41

1.6K0

前言

前面我们介绍过 MKDocs 的基础用法（MKDocs 入门）。很多同学都表示非常香，但是默认的主题不够美观，虽然我们可以通过内置的 readthedocs 主题来改善，但是还不够美，几天我们就一起来尝试一款比较现代的 MKDocs 主题 material。

关于 material

material 主题是基于 MKDocs 的面向现代化技术文档网站的一个主题，非常的漂亮。

呆猫

首先我们 mkdocs init 初始化一个 MKDocs 项目。

然后我们 pip install mkdocs-material 下载 material 主题。

最后我们启动项目时指定主题为 material。

怎么样，相比 readthedocs，material 的效果还是比较清新现代的。

material 配置

通常我们会将主题配置到 mkdocs.yaml 中，而非命令行指定。

所以我们需要将主题和 markdown 的高亮配置写到配置文件中。

site_name: My Docs
theme:
  name: material
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

配置主题到 mkdocs.yaml 后，启动服务不需要指定主题了。直接 mkdocs serve 即可

代码高亮和标题

material 不但支持代码高亮还支持代码标题。

```python title='demo.py'
def sayhi():
    return "hi,Python全栈开发"
```

不但如此，material 还支持代码自由注释，并且交互良好。

```python title='demo.py'
def sayhi():
    return "hi,Python全栈开发" # (1)
```

1. 这是我自由注释的内容，欢迎关注我的公众号。

好看的提示框

提示框的配置：

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
theme:
  icon:
    admonition:
      note: octicons/tag-16
      abstract: octicons/checklist-16
      info: octicons/info-16
      tip: octicons/squirrel-16
      success: octicons/check-16
      question: octicons/question-16
      warning: octicons/alert-16
      failure: octicons/x-circle-16
      danger: octicons/zap-16
      bug: octicons/bug-16
      example: octicons/beaker-16
      quote: octicons/quote-16

md 内容：

!!! note "这是 note 类型的提示框"
提示：更多精彩内容记得关注我啊

!!! success "这是 success 类型的提示框"
成功！

!!! failure "这是 failure 类型的提示框"
失败！

!!! bug "这是 bug 类型的提示框"
发现一个 bug，请尽快修复！

对于提示框中很多内容的场景，该如何处理呢？material 支持提示框的折叠。

!!! --> ??? 即可。

md 内容：

??? note "这是 note 类型的提示框"
提示：更多精彩内容记得关注我啊

    第二行

    第三行

    第四行

    第五行
    ...

最后

以上 material 只展示了部分功能，material 还支持单词缩写、按钮、数据表格、mermaid、锚、字符格式化、Emoji、Icon、图片、数学公式等。总之，很强大。

最后，希望我的分享能够对你有所帮助！

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

如有侵权请联系 cloudcommunity@tencent.com 删除

markdown

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度