Build site with MkDocs

Notes
,

What is MkDocs?

Accroding to the description from the offical site of 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 introductory tutorial, then check the User Guide for more information.

With MkDocs, you can generate a static site in a minute and deploy it on your server or github pages.

Installation

First, make sure that Python was installed on you PC and install MkDocs with follow command.

1
pip install mkdocs

Create a new project

1
2
mkdocs new my-project
cd my-project

image-20210614210231958

mkdocs.yml is the configuration file. The docs folder contains your markdown source files.

1
mkdocs serve

You can preview the site at http://127.0.0.1:8000/ in your browser.

Deploying

Create a Github repository. clone to your local directory and add site/ to .gitignore

1
2
3
4
5
mkdir docs
cd docs
mkdocs new .
mkdocs build
mkdocs serve

Write your docs in the folder docs. Then run the command:

1
mkdocs gh-deploy --clean

It will create a gh-pages branch in your respository and deploy the static site on your github page. Set the default branch to built github pages.

image-20210619154133068

You can access you site at https://{username}.github.io/{projectname}.

Use MkDocs-Material Theme

1
2
3
4
Install gtk3-runtime-3.xxx-ts-win64.exe at https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases

pip install --upgrade setuptools
pip install mkdocs-material

Configure the sites in mkdocs.yml refer to the official documents.

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
site_name: Notebook
site_url: https://landfill.cc/wiki/
#site_description: cs WIKI
#copyright: Copyright © 2020 [Landfill](https://www.landfill.cc/)
nav: 
- Home: index.md
#  - DEV: dev.md 
- Documents: 
  - Usage : test/usage.md
  - Tutorial: test/tutorial.md
- Data Structure:
  - AVL Tree: DataStructure/about.md
- OS: 
  - OS NOTES: OS/os.md
- test: test.md
 

#主题
theme:
  name: material
  #custom_dir: material
  language: 'zh'  # 配置语言
  palette:  # 颜色
    # - scheme: default
    primary: indigo
    accent: indigo
    #   toggle:
    #     icon: material/toggle-switch-off-outline
    #     name: Switch to dark mode
    # - scheme: slate
    #   primary: indigo
    #   accent: indigo
    #   toggle:
    #     icon: material/toggle-switch
    #     name: Switch to light mode
  features:
    - navigation.tabs # horizon tabs 
    - navigation.tracking
    - navigation.expand
    - navigation.top
  #custom_dir: 'docs/resources/'
  font:
    text: Roboto
    code: Roboto Mono

markdown_extensions:
  - admonition  # 提示块
  - footnotes  # 脚注
  - meta  # 定义元数据，通过文章上下文控制，如disqus
  - pymdownx.caret  # 下划线上标
  - pymdownx.tilde  # 删除线下标
  - pymdownx.critic  # 增加删除修改高亮注释，可修饰行内或段落
  - pymdownx.details  # 提示块可折叠
  - pymdownx.inlinehilite  # 行内代码高亮
  - pymdownx.mark  # 文本高亮
  - pymdownx.smartsymbols  # 符号转换
  - pymdownx.superfences  # 代码嵌套在列表里
  - codehilite:    # 代码高亮，显示行号
      guess_lang: false
      linenums: true
  - toc:  # 锚点
      permalink: true
#  - pymdownx.arithmatex  # 数学公式
  - pymdownx.betterem:  # 对加粗和斜体更好的检测
      smart_enable: all
#  - pymdownx.emoji:  # 表情
#      emoji_generator: !!python/name:pymdownx.emoji.to_svg
#  - pymdownx.magiclink  # 自动识别超链接
  - pymdownx.tasklist:  # 复选框checklist
      custom_checkbox: true

extra:
  search:
    language: 'jp'

#扩展样式
# extra_css:
#   - resources/css/extra.css