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

更新於 2024/01/19發佈於 2023/08/28閱讀時間約 6 分鐘

各位你們好：

今天我們來聊一下如何使用 MkDocs 快速建立文件網頁，並將其部署在 Read The Docs 上。（這篇文章用語有和 chatgpt 討論過）。

許多人可能會有建立自己的說明文件、網頁、部落格等需求。當然，最正規的方式是學習 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