搭建MkDocs Material

发表于 | | 阅读次数:
字数统计: 490 | 阅读时长 ≈ 2

前言

MkDocs是一个开源的静态站点生成器，支持Markdown，适合发布文档。
而MkDocs Material基于Material设计风格，更加简洁美观，例如OI Wiki就是基于MkDocs Material搭建的。
源代码可以在GitHub上查看。

安装

MkDocs作为Python模块发布到了PyPI，因此可以通过Python包管理器pip安装：

1
2
pip install mkdocs
pip install mkdocs-material

如果下载缓慢，可以参考之前的文章更换下载源。

搭建

初始化

执行命令

1
mkdocs new new-project

生成new-project目录并初始化，其中mkdocs.yml是配置文件。

进入目录，执行

1
mkdocs serve

即可在http://127.0.0.1:8000/中预览。
按Ctrl+C结束预览。

配置

在mkdocs.yml中，添加以下内容：

1
2
theme:
  name: material

MkDocs就更换到了Material主题。

主题还可以进一步配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
theme:
  name: material
  language: zh # 语言，默认为en
  features:
    tabs: true # 显示顶部导航栏
  palette: # 颜色
    primary: indigo # 主色
    accent: indigo # 辅助色
  font: # 字体
    text: Ubuntu # 正文，默认为Roboto
    code: Ubuntu Mono # 代码，默认为Roboto Mono
  favicon: /images/favicon.ico # 网页图标
  logo: /images/icon.png # 顶端图标

注意，资源文件如/images/文件夹应放在/docs/内。

为了支持更多的Markdown语法，可以开启以下扩展：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
markdown_extensions:
  - markdown.extensions.admonition
  - markdown.extensions.codehilite:
      guess_lang: false
  - markdown.extensions.def_list
  - markdown.extensions.footnotes
  - markdown.extensions.meta
  - markdown.extensions.toc:
      permalink: true
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:pymdownx.emoji.twemoji
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

写作

基本配置完了之后，可以在mkdocs.yml下添加目录：

1
2
3
4
5
6
nav:
  - Introduction: index.md
  - Install:
    - Windows: install/windows.md
    - Linux: install/linux.md
    - macOS: install/macos.md

这是一个简单的例子。
必须要有index.md。
windows.md放在new-project/docs/install/中，以此类推。

生成

执行命令

1
mkdocs build

后会生成/site/目录，其中有站点的静态文件。
将这些静态文件全部复制到你的站点中即可。

0%