用MkDocs从Markdown生成Blog¶

概要：使用MkDocs和Material for MkDocs主题，从Markdown文件生成Blog。

安装MkDocs¶

yay -S mkdocs
你会发现运行不了（因为#2306），所以我们需要手动降级python-lunr到0.5.8
去AUR网站上找到0.5.8版本的页面，然后从这个链接下载PKGBUILD.
解压后在有PKGBUILD的目录运行makepkg -si来安装（降级）

创建MkDocs项目¶

mkdocs new my-project
会创建项目一个文件夹，里面有doc文件夹，那里面是用来放所有Markdown文件的
mkdocs.yml的设置参数：文档
生成的网页的路径是由文件名决定的，但是网页里导航菜单里的标题是由Markdown里的标题决定的
启动测试服务器（会根据文件变化实时更改）：mkdocs serve
生成静态网页：mkdocs build

加上主题¶

pip install mkdocs-material
主题会在mkdocs.yml加一些新的选项用来配置主题
最基础的，加上这两行应用这个主题：
```
theme:
  name: material
```
更多的设置，参考文档和文档

加上创建&更改日期¶

下载安装我改过的plugin：

git clone https://github.com/PegasisForever/mkdocs-git-revision-date-localized-plugin.git
cd mkdocs-git-revision-date-localized-plugin
pip install .

创建<project-root>/overrides/partials/source-date.html：

<hr>
<div class="md-source-date">
  <small>
    {% if page.meta.git_creation_date_localized %}
      Created at: {{ page.meta.git_creation_date_localized }}
    {% endif %}
    <br/>
    {% if page.meta.git_revision_date_localized %}
      Last update: {{ page.meta.git_revision_date_localized }}
    {% endif %}
  </small>
</div>

在mkdics.yml加上这些：（因为plugins不写的话search是默认在的，所以我们现在明确写了plugins的话需要手动加search）（更多的配置选项去看readme）
```
theme:
  custom_dir: overrides
plugins:
  - search
  - git-revision-date-localized:
      enable_creation_date: true
```

创建git仓库并commit

git init
echo "site" > .gitignore    # 忽视生成的文件
git add -A
git commit -m "$(date)"     # fish: git commit -m (date)

Markdown扩展¶

PyMdown可以扩展Markdown的语法，具体列表见extensions

安装¶

应该已经跟着mkdocs-material安装好了

pip install pymdown-extensions

用法¶

把pymdownx.xxxx加到mkdocs.yml的markdown_extensions:下

比如我想加Keys：

markdown_extensions:
  - pymdownx.superfences

自定义文章排序&标题¶

安装awesome-pages：pip install mkdocs-awesome-pages-plugin
mkdocs.yml加上：
```
plugins:
  - awesome-pages
```
如果mkdocs.yml里有nav或者pages项要删掉，否则这个插件不会生效

在每个需要自定义排序的文件夹下创建.pages文件：

nav:
    # 所有文件名都不需要加路径
    - Welcome: index.md   # 自定义文章导航菜单标题
    - AUR Notes.md        # md文件
    - Python Handouts     # 子目录
    - ...                 # 所有其它的文件

此Blog的`.pages`¶

`public/.pages`¶

nav:
  - Welcome: index.md
  - Python Handouts
  - ...

`public/Python Handouts/.pages`¶

nav:
  - index.md
  - Introduction to Programming Languages and Python.md
  - First Line of Code.md
  - Basic Terms.md
  - Values.md
  - Variables.md
  - Operators.md
  - Basic Function.md
  - Control Flow.md
  - More About If Statement.md
  - Code Readability.md
  - Lists and Tuples.md
  - Advanced Function.md
  - Import Statement.md
  - Object-Oriented Programming.md
  - How to Use a Class.md
  - How to Create a Class.md
  - Use Processing.py to Build GUI Applications.md

加上评论区¶

评论基于disqus，参考文档

disqus网站上也有一些设置，记得去看

修bug¶

在列表中的代码块显示不正常¶

issue：https://github.com/mkdocs/mkdocs/issues/2153

通过以下方式可以暂时解决

pip install pymdown-extensions（应该已经跟着mkdocs-material安装好了）

mkdocs.yml加上这么一条：

markdown_extensions:
  - pymdownx.superfences

Disqus推荐不显示¶

很奇怪，设置里开了却不显示，去论坛问了这个问题：

https://disqus.com/home/channel/discussdisqus/discussion/channel-discussdisqus/embed_site_recommendations_doesnt_show_up/

Instant Loading启用时Disqus不显示¶

我fork了一下，解决了

pip install git+git://github.com/PegasisForever/mkdocs-material@fix_disqus_instant_loading#egg=mkdocs-material

pr：https://github.com/squidfunk/mkdocs-material/pull/2487

Instant Loading不对mkdocs-section生效¶

issue：https://github.com/oprypin/mkdocs-section-index/issues/3

Buggy title bar shadow¶

我fork了一下，解决了

pip install git+git://github.com/PegasisForever/mkdocs-material.git@fix_buggy_header_shadow2#egg=mkdocs-material

pr：https://github.com/squidfunk/mkdocs-material/pull/2494

快捷脚本¶

`build.sh`¶

#! /bin/sh

git add -A || exit
git commit -m "$(date)" || exit
mkdocs build

Markdown编辑器¶

Typora! 世界最强Markdown编辑器，没有之一

需要稍微改几个设置来更好符合写blog的场景以及MkDocs：

此Blog的`mkdocs.yml`¶

site_name: Pega's Notes
site_description: A collection of my personal notes, published online in case anyone found it useful.
docs_dir: public
site_dir: build
theme:
  name: material
  custom_dir: .overrides
  font:
    text: Fira Sans
    code: JetBrains Mono
  palette:
    primary: teal
    accent: teal
  logo: pega_logo_filled.svg
  favicon: favicon.png
  features:
    - navigation.instant
    - toc.integrate
    - search.suggest
plugins:
  - awesome-pages
  - section-index
  - search:
      lang:
        - en
  - rss:
      length: 10000
  - git-revision-date-localized:
      enable_creation_date: true
      timezone: America/Toronto
      locale: en
markdown_extensions:
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.arithmatex
  - pymdownx.superfences
  - pymdownx.magiclink
  - pymdownx.tilde
  - pymdownx.caret
  - pymdownx.emoji
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - toc:
      permalink: true
extra:
  homepage: https://pegas.is/
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/PegasisForever
    - icon: fontawesome/brands/instagram
      link: https://www.instagram.com/__pegasis/
extra_css:
  - extra.css
extra_javascript:
  - extra.js
site_url: https://notes.pegas.is/
copyright: Copyright &copy; 2021 Pegasis
site_author: Pegasis

以后可能用到¶

画流程图：Draw.io Exporter

一些链接¶

Mkdocs
- 官网
- mkdocs.yml文档
- GitHub
- Wiki
- Theme List
- Plugin List
Material for MkDocs主题
- 官网
- GitHub
mkdocs-git-revision-date-localized-plugin
- GitHub
PyMdown
- 扩展列表

Last update: March 27, 2021
Created: March 24, 2021