采用Material主题

Documentation that simply works

Material for MkDocs is a powerful documentation framework on top of MkDocs, a static site generator for project documentation.

安装 mkdocs-material#

Getting started - Installation

$ pip install mkdocs-material
# or 
$ pip3 install mkdocs-material
# or 
$ python3 -m pip install mkdocs-material

设置主题为 material#

Getting started - Creating your site - Configuration

Minimal configuration：

在 mkdocs.yml 配置文件中，指定主题 material，替换默认的 mkdocs 主题：

# 指定主题
theme:
  name: material

Setup & Customization#

Advanced configuration:

Material for MkDocs comes with many configuration options. The Setup section explains in great detail how to configure and customize colors, fonts, icons and much more

Site structure
Appearance
Content
Optimization

Getting started - Customization

Adding assets
Extending the theme
Theme development

MkDocs Material Preview#

MkDocs Material Preview - Visual Studio Marketplace: A VS Code extension that enhances the built-in Markdown preview to render Material for MkDocs and Zensical components that are not supported by the default Markdown renderer.

它通过附加插件来扩展 VS Code 内置的 Markdown 解析器--markdown-it，从而增强支持渲染/预览以下 Material 特性组件：

Admonitions — !!! type "title" (standard), ??? type (collapsible), ???+ type (collapsible, open)
Content Tabs — === "Tab Title" with CSS-only tab switching
Code Enhancements — title="file.py", hl_lines="2 4-6", linenums="1" on fenced code blocks