Mkdocs Start

  MkDocs 快速上手教學, 主要就是編輯 yml 檔案去更改 Theme 和 doc 語法

Theme

安裝完後內建 Read The Docs Theme最為普及, 其他 Theme 也可參考這裡下載 ,

更改使用的 Theme 於 mkdocs.yml 放入 theme: readthedocs 並 mkdocs build 即可完成, e.g.

site_name: My Docs
theme: readthedocs

 

Popular Extension

Install method:

pip3 install Pygments pymdown-extensions

將以下模組放入 yml file:

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

個人常用:

Pygments

• CodeHilite

pymdown-extensions

PyMdown Extensions 集合了與許多重要且實用的功能, 強烈建議安裝.

• Details¶

Details 提供縮合功能, 並可以支援不同顏色根據 e.g. note, question, warning etc.:

• Mark¶

Mark 提供 highlight text like it was marked with a text marker. e.g. ==...==.

• SuperFences¶

SuperFences 提供 code block 顯示正常於 Details 開合區塊內

Not Support

1. 圖片大小, 但可以使用一般 html 語法完成
2. 超連結開啟分頁, 但可以使用一般 html 語法完成

Reference:

• https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#details