基于Material for MkDocs搭建静态文档¶

Mkdocs 可以十分方便的建立一个静态文档，比如 OI Wiki，此文档也是基于 Mkdocs

此文档内容仅是基于个人经历的理解

需要的用到的工具：Markdown编辑器，python3

安装/初始化/配置范例¶

安装¶

利用 python3 自带的 pip 工具在 cmd 中输入

pip install mkdocs mkdocs-material

如果后面提示 'mkdocs' 不是内部或外部命令.... 的话就需要自己加一下环境变量

初始化¶

在你想要新建文档的目录启动 cmd，并输入以下命令

mkdocs new my-project

然后打开新建的文件夹打开 mkdocs.yml，以下列出我写此文档时的配置并配上了注释作为参考

# site
site_name: hucorz's Docs                      # 文档的名字，会体现在左上角
site_url: https://hucorz.github.io/myDoc/     # 网站的链接，似乎点击左上角的logo后会进去，我也没做实验

# repo
repo_name: 'hucorz/myDoc'                     # github仓库的名字，会体现在右上角
repo_url: https://github.com/hucorz/myDoc     # github仓库的链接，点击右上角的logo后会进去

nav:                                          # 导航页，具体内容要基于自己文档的内容
  - Home: 'index.md'                          # : 后面是文件的名字，前面是文档中显示的名字，可以嵌套
  - Makrdown: 'Markdown.md'
  - OI: 
    - 参考: 'OI/参考.md'
    - 数论: 'OI/数论.md'
    - 计算几何: 'OI/计算几何.md'
    - 图论: 'OI/图论.md'
    - 数据结构: 'OI/数据结构.md'
    - 字符串: 'OI/字符串.md'
    - 其他: 'OI/其他.md'
    - STL: 'OI/STL.md'
  - 课程笔记: 
    - 参考: '课程笔记/参考.md'
    - 数据库系统: '课程笔记/数据库系统.md'

theme:                                        
  name: 'material'                            # 主题，就用 material
  features:                                   # 这后面是主题的配置，具体我会写在文档后面
    - navigation.tabs
    - navigation.tabs.sticky
  palette:
    primary: 'white'                          # 配色
    accent: 'indigo'
  logo: 'img/cat-solid.svg'                   # 左上角logo
  icon: 
    repo: fontawesome/brands/github-alt # repo的logo
  favicon: 'img/favicon.ico'                  #网页图标

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.highlight                        # 代码高亮
  - pymdownx.superfences
  - toc:
      permalink: true                         # 每个标题后面的 锚链接
      #toc_depth: 2                           # table of content 显示的级数，0就不会显示

extra_javascript:
  - javascripts/config.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

plugins:
  - search:
      lang: ja                               # 实测搜索语言改成日本可以支持中文搜搜

部署 github¶

首先需要一个 github 账号，然后新建一个空仓库，并利用 git 将仓库 clone 到本地

仅讲一下我遇到的问题：

Failed to connect to github.com port 443: Timed out

解决方法：给 git 设置代理

科学上网时打开 win10 设置里的代理设置，找到代理的地址和端口

git config --global http.proxy 172.17.18.80:8080  # 后面是 地址:端口

查看是否成功

git config --get http.proxy

克隆成功后把 .yml 和 docs 放在克隆文件夹里，然后在此文件夹启动 cmd，输入以下指令即可部署

mkdocs gh-deploy

美化配置¶

官方文档

文档名称¶

site_name: hucorz's Docs                    
site_url: https://hucorz.github.io/myDoc/

文档主题¶

theme:                                        
  name: 'material'

配色¶

配色相关配置

theme:
 palette:
    primary: 'white'
    accent: 'indigo'

导航页¶

导航页相关配置

features: 
    - navigation.tabs
    - navigation.tabs.sticky

logo && favicon¶

文档的 logo && favicon¶

logo && favicon 相关配置

theme:    # 这两个我都是下下来后用的
    logo: 'img/cat-solid.svg' 
    favicon: 'img/favicon.ico'

repo 的 logo¶

repo 相关配置

你需要先在配置中添加 repo 的名字和 url

repo_name: 'hucorz/myDoc'
repo_url: https://github.com/hucorz/myDoc

然后 logo 参考的官方文档：

theme:
  icon: 
    repo: fontawesome/brands/github-alt

扩展¶

markdown扩展¶

数学公式

MathJax - Material for MkDocs

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/config.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

代码高亮

Code blocks - Material for MkDocs

markdown_extensions:
  - pymdownx.highlight      # code hilight
  - pymdownx.superfences

toc（table of content）

Setting up navigation - Material for MkDocs

markdown_extensions:    # 这2个都是和每个markdown文档的标题有关
  - toc:
      permalink: true   # 开启每个标题后面的 锚链接
      #toc_depth: 2     # toc显示的级数,越高显示的越多，不写都显示，0不显示

支持中文搜索¶

Setting up site search - Material for MkDocs

plugins:
  - search:
      lang: ja

一些问题的解决办法¶

数学公式不能正常显示：

在 $$ 前后加一行空行

参考¶

1.介绍 - 基于 Material for MkDocs 搭建静态网页

Material for MkDocs - Material forMkDocs

Failed to connect to github.com port 443: Timed out_天生我材必有用-CSDN博客