用 MkDocs 10 分鐘建立網頁（或文件、部落格）

你好：

今天來講：用 MkDocs 快速建立文件網頁，並部署在 Read The Docs 上。
(南瓜標記🎃 2023082901號文章)

很多人可能會有需要自己建立說明文件、網頁、部落格、等等的需求。當然最正規的方式還是去學 javascript, html, css 之類的。但我們又不是網頁巫師。我們可能只是做資料分析、或是一般科學研究、或是其他各種業務的，那怎麼辦？

其實我一直有在用的是 R 語言生態系裡面的，例如 blogdown (用 rmarkdown 寫文件，hugo 生成網站) 或是現在最新的 Quarto (用 qmd 寫文件，生成 html)。 然後部署在 netlify 上面。或是最最最簡單的，（幾乎一鍵完成），學術相關的個人網頁、課程網頁、文件筆記、等等的，就是用 Wowchemy 家的東西。🚩 這些東西以後有機會再寫文章跟大家講解。

今天來講的是，一種相對簡單粗暴的作法。也就是純寫 markdown 文件，然後上傳到 github（或乾脆直接在 github 上面寫好），然後他會自動生成網頁的方式（其實我剛剛上面講的所有方式也都可以這樣操作啦）。

Step 1. MkDocs 生成文件（在桌面）

這部份的詳細內容可以去參考 MkDOcs 的文件。寫得非常詳細了。或是你去 google 也可以搜到一堆教學。這篇文章是記錄我自己創見的流程給你參考。（主要是我自己如果要再做一次，可以完全照這個說明操作）

打開你的終端，可能是 Terminal，或是命令提示字元 (Windows)。首先要安裝mkdocs，輸入下列指令：pip install mkdocs。（可知這是一個 python 的套件）。安裝好了，接下來就輸入下列指令（my-project 可以換成你想要的名稱）：

mkdocs new my-project 
cd my-project

也就是建立一個名為「my-project」的資料夾，cd 會幫你切到那個資料夾底下。

再來一個重要指令是生一個成品給你看：

mkdocs serve

他可能會出現一個網址例如 http://127.0.0.1:8000/，點下去就會在瀏覽器顯示一個基本頁面。

基本上就這樣。其他新增文件、修改文件等等，其實你直接點去資料夾裡面，像個麻瓜一樣即可。

(以下的部份因為方格子系統問題，原本內容都沒存到 😡。所以簡略寫一下。)

Step 2. 上傳 Github

先開個 github 帳號，然後開個 repo。內容自行 google。

• 上傳檔案 mkdocs.yml 到 repo。
• 新增檔案 docs/index.md, docs/about.md。內容複製本將上的同名檔案。因為 github 不能新資料夾，所以自己寫。
• 新增檔案 .readthedocs.yaml，這是部署到 readthedocs 用的。詳細內容請看 Configuration file tutorial mkdocs 部份。內容如下：

# Read the Docs configuration file for MkDocs projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

mkdocs:
  configuration: mkdocs.yml

# Optionally declare the Python requirements required to build your docs
python:
  install:
  - requirements: docs/requirements.txt

• 新增檔案 docs/requirements.txt。安裝必要的 python 套件。例如：

mkdocs
mkdocs-terminal
mkdocs-jupyter

Step 3. 部署到 readthedocs.io

先開個 readthedocs 帳號。內容自行 google。

• Import a Project，然後連結你要的 github Repository。
• 一路按下去。
• 第一次應該不會成功。因為預設檔案是 sphinx，要改成 mkdocs。所以進去你的新建的專案，進去 Admin，Advanced Settings，在 Documentation type* 的地方選擇 mkdocs。
• 再重新 build 一次。

Discussion

這邊討論幾種可以修改的地方：（網址抱歉懶得連結了，被方格子編輯器氣到 😤）

• 修改主題，請見 https://www.mkdocs.org/user-guide/choosing-your-theme/
• 第三方主題，請見 https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
• 支援數學，請見 https://squidfunk.github.io/mkdocs-material/reference/math/
• 支援 jupyter，請見 https://github.com/danielfrg/mkdocs-jupyter
• 支援搜尋，就在 plugins 增加 search。

他們的設定方式寫得都很清楚簡單，網頁麻瓜也能懂。我的 mkdocs.yml 參考設定如下（部份）：

theme: 
  name: terminal
  palette: dark

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

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

plugins:
  - search
  - mkdocs-jupyter

See Also

• MkDocs
• Read the Docs: documentation simplified

🎃

這篇文章就到這邊。
你讀完之後有什麼想法嗎？留言告訴我~