title: Mkdocs 搭建博客指北，以及推荐 Mkdocs-Materials 主题

description: 最近在看 fastAPI 的文档，无意中发现许多 Python 的库的官方文档都是用的 Mkdocs-Materials

redirect: 2020-06-17-mkdocs-material-turtorial

description: 最近在看 fastAPI 的文档，无意中发现许多 Python 的库的官方文档都是用的 Mkdocs-Materials

什么是 Mkdocs

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introduction below, then check the User Guide for more info.

Mkdocs-Materials

Create a branded static site from a set of Markdown files to host the documentation of your Open Source or commercial project – customizable, searchable, mobile-friendly, 40+ languages. Set up in 5 minutes.

Quick Start

  1. # 安装
  2. pip install mkdocs-material
  3. # 新建项目
  4. mkdocs new project-doc
  5. # 将 markdown 文件放入 doc 文件夹
  6. # 构建
  7. mkdocs build # 生成 html
  8. # 本地服务
  9. mkdocs serve
  10. # 打开
  11. start 127.0.0.1:8000

使用

官方参考 mkdocs.yml

  1. # Project information
  2. site_name: Material for MkDocs
  3. site_url: https://squidfunk.github.io/mkdocs-material/
  4. site_author: Martin Donath
  5. site_description: >-
  6.   Create a branded static site from a set of Markdown files to host the
  7.   documentation of your Open Source or commercial project – customizable,
  8.   searchable, mobile-friendly, 40+ languages
  9. # Repository
  10. repo_name: squidfunk/mkdocs-material
  11. repo_url: https://github.com/squidfunk/mkdocs-material
  12. edit_uri: ""
  13. # Copyright
  14. copyright: Copyright © 2016 - 2020 Martin Donath
  15. # Configuration
  16. theme:
  17.   name: null
  18.   custom_dir: material
  19.   # 404 page
  20.   static_templates:
  21.     - 404.html
  22.   # Don't include MkDocs' JavaScript
  23.   include_search_page: false
  24.   search_index_only: true
  25.   # Default values, taken from mkdocs_theme.yml
  26.   language: en
  27.   features:
  28.     - tabs
  29.     #- instant
  30.   palette:
  31.     scheme: default
  32.     primary: indigo
  33.     accent: indigo
  34.   font:
  35.     text: Roboto
  36.     code: Roboto Mono
  37.   icon:
  38.     logo: logo
  39.   favicon: assets/favicon.png
  40. # Plugins
  41. plugins:
  42.   - search
  43.   - minify:
  44.       minify_html: true
  45. # Customization
  46. extra:
  47.   social:
  48.     - icon: fontawesome/brands/github
  49.       link: https://github.com/squidfunk
  50.     - icon: fontawesome/brands/gitter
  51.       link: https://gitter.im/squidfunk/mkdocs-material
  52.     - icon: fontawesome/brands/docker
  53.       link: https://hub.docker.com/r/squidfunk/mkdocs-material/
  54.     - icon: fontawesome/brands/twitter
  55.       link: https://twitter.com/squidfunk
  56.     - icon: fontawesome/brands/linkedin
  57.       link: https://linkedin.com/in/squidfunk/
  58.     - icon: fontawesome/brands/instagram
  59.       link: https://instagram.com/squidfunk
  60. # Extensions
  61. markdown_extensions:
  62.   - markdown.extensions.admonition
  63.   - markdown.extensions.attr_list
  64.   - markdown.extensions.codehilite:
  65.       guess_lang: false
  66.   - markdown.extensions.def_list
  67.   - markdown.extensions.footnotes
  68.   - markdown.extensions.meta
  69.   - markdown.extensions.toc:
  70.       permalink: true
  71.   - pymdownx.arithmatex
  72.   - pymdownx.betterem:
  73.       smart_enable: all
  74.   - pymdownx.caret
  75.   - pymdownx.critic
  76.   - pymdownx.details
  77.   - pymdownx.emoji:
  78.       emoji_index: !!python/name:materialx.emoji.twemoji
  79.       emoji_generator: !!python/name:materialx.emoji.to_svg
  80.   # - pymdownx.highlight:
  81.   #     linenums_style: pymdownx-inline
  82.   - pymdownx.inlinehilite
  83.   - pymdownx.keys
  84.   - pymdownx.magiclink:
  85.       repo_url_shorthand: true
  86.       user: squidfunk
  87.       repo: mkdocs-material
  88.   - pymdownx.mark
  89.   - pymdownx.smartsymbols
  90.   - pymdownx.snippets:
  91.       check_paths: true
  92.   - pymdownx.superfences
  93.   - pymdownx.tabbed
  94.   - pymdownx.tasklist:
  95.       custom_checkbox: true
  96.   - pymdownx.tilde
  97. # Page tree
  98. nav:
  99.   - Home: index.md
  100.   - Getting started: getting-started.md
  101.   - Extensions:
  102.     - Admonition: extensions/admonition.md
  103.     - CodeHilite: extensions/codehilite.md
  104.     - Footnotes: extensions/footnotes.md
  105.     - Metadata: extensions/metadata.md
  106.     - Permalinks: extensions/permalinks.md
  107.     - PyMdown: extensions/pymdown.md
  108.   - Plugins:
  109.     - Search: plugins/search.md
  110.     - Minification: plugins/minification.md
  111.     - Revision date: plugins/revision-date.md
  112.     - Awesome pages: plugins/awesome-pages.md
  113.   - Releases:
  114.     - Upgrading to 5.x: releases/5.md
  115.     - Upgrading to 4.x: releases/4.md
  116.     - Changelog: releases/changelog.md
  117.   - Customization: customization.md
  118.   - Data privacy: data-privacy.md
  119.   - Contributing: contributing.md
  120.   - License: license.md
  121. # Google Analytics
  122. google_analytics:
  123.   - !!python/object/apply:os.getenv ["GOOGLE_ANALYTICS_KEY"]
  124.   - auto

使用 Mkdocs Materials 全文搜索

因为 Mkdocs 自带的全文搜索是使用 lunr.js 写的，所以=2020-06-17=前还不支持中文
我是了下网上说的设置为日文，反正在我的版本也不行
而且 Mkdocs-Material 主题没有用 Mkdocs 自带的实现，要记得设置 search_index_only: true

部署 Github pages

每次 gh-deploy 后生成的文件会被 push 到 gh-pages 分支，尽量不要修改 site 文件夹里的内容，修改了就要 git pull
刚开始我没有在 site 文件夹里写 CNAME 导致每次部署后都刷新了 pages 的自定义域名，当然如果你用仓库的域名就另说了

PyMdown 扩展

添加配置

markdown_extensions:
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tabbed
  - pymdownx.tilde

Details

??? success
   Content.
??? warning classes
   Content.

MagicLink

自动链接

=== “Output”
- Just paste links directly in the document like this: https://google.com.
- Or even an email address: fake.email@email.com.
=== “Markdown”
markdown - Just paste links directly in the document like this: [https://google.com. -](https://google.com.%20-) Or even an email address: fake.email@email.com.

短链接

=== “Output”
_@_facelessuser
=== “Markdown”
markdown @facelessuser
支持的 provider

{
    "bitbucket": ['dashboard', 'account', 'plans', 'support', 'repo'],
    "github": ['marketeplace', 'notifications', 'issues', 'pull', 'sponsors', 'settings', 'support'],
    "gitlab": ['dashboard', '-', 'explore', 'help', 'projects'],
    "twitter": ['i', 'messages', 'bookmarks', 'home']
}

模板

===--8<--===
filename
filename2
===--8<--===

代码

#!/bin/bash
STR="Hello World!"
echo $STR

#include 
int main(void) {
  printf("hello, world\n");
}

#include <iostream>
int main() {
  std::cout << "Hello, world!\n";
  return 0;
}

using System;
class Program {
  static void Main(string[] args) {
    Console.WriteLine("Hello, world!");
  }
}

表格

=== "Tab 1"
    Markdown **content**.
    Multiple paragraphs.
=== "Tab 2"
    More Markdown **content**.
    - list item a
    - list item b
===! "Tab A"
    Different tab set.
=== "Tab B"

More content.

<a name="b60ec8b0"></a>
#### 待办
=== "Output"<br />- [X] item 1<br />* [X] item A<br />* [ ] item B<br />more text<br />+ [x] item a<br />+ [ ] item b<br />+ [x] item c<br />* [X] item C<br />- [ ] item 2<br />- [ ] item 3<br />=== "Markdown"<br />`markdown - [X] item 1 * [X] item A * [ ] item B more text + [x] item a + [ ] item b + [x] item c * [X] item C - [ ] item 2 - [ ] item 3`
<a name="6f5726d2"></a>
### 启用 Admonitionn
```yaml
markdown_extensions:
  - admontion

用法

!!! note
    this is a note

效果
!!! note
this is a note
Support Types: