各位你們好：
今天我們來聊一下如何使用 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
See Also
🎃
這篇文章就到這邊。
你讀完之後有什麼想法嗎？留言告訴我~
