一種半自動的最小可行寫作方案

• JW
• 2025-09-01
• 2024-02-16

原文：單純使用 .md 與 .ipynb 格式寫作的最小可行方案

Problem.

你想用一個簡單隨手可得的編輯器（例如 colab，因為可用 md, ipynb, 可支援 python, r, julia），並且寫好後可以一鍵發佈。

你想單純使用 .md 紀錄純文字、簡單的數學式 (支援 latex)、表格與程式。如果需要有執行結果的，則用 .ipynb 的檔案來紀錄和執行。最後，只需要最非常簡單的事情，甚至不用轉檔，就可以彙整。

我這麼說，就是因為 Quarto 也很好用，但他是要轉檔。quarto 在 rstudio 上寫好後，也是可以一鍵發布到 Quarto Pub 上面。 而且可調整性更高。 但是他就是還是需要安裝 r, rstudio, quarto 等軟體，而且主要是在本機上寫，比較難跨機器。如果只是想做簡單編輯、改幾個字，還得大費周章開啟 rstudio.

一種最小可行方案： mk/ipynb --> github --> mkdocs --> readthedocs 。

這種方法的好處是，編輯器取得非常容易。只要在 google drive 中開啟即可。或是在 github 上直接寫 md. 後續的事只要第一次設定好，基本就是半自動了。

Solution.

使用 colab 當編輯器，用 github 當後台，用 mkdocs 當引擎，用 readthedos 當部署。

Step 1. Install MkDocs

安裝方式，在 mac 系統上，用 homebrew 就可以了。

# general
brew install mkdocs

# for material theme
brew install mkdocs-material

在 windows 系統上，就參考官網： mkdcos

pip install mkdocs

Step 2. Usage

使用上，就按照官網指示： 建立一個新資料夾。

# create a new project
mkdocs new my-project

# go into the project's file
cd my-project

# show in your local computer
mkdocs serve

Step 3. Add Files

• 使用 markdown 檔案應該是基本可行的。
• 使用 jupyter 檔案則加上外掛就可行。（如下節所示）

Step 3.1. Add a requirement.txt in the docs file, 這一步是為了安裝所需要的 python 套件。例子：

mkdocs
mkdocs-jupyter
mkdocs-material

Step 3.2. Add a .readthedocs.yaml in the file

這是上傳到 readthedocs 上時會需要的。通常部署時參考他建議的寫法就行。例子：

# 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.12"

mkdocs:
  configuration: mkdocs.yml

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

Step 3.3. change your mkdocs.yml

最後，就是修改 mkdocs.yml 中的設定。 因為本文目標是「最小可行」，因此就是字型什麼幾乎不改，目錄也不改，都用預設值。唯二需要增加的是：

• latex 語法支援。詳細設定方式請參考 Material for MkDocs - Math
• jupyter 格式支援。在 plugins 加入 - mkdocs-jupyter。

例子：

site_name: YOUR_SITE_NAME

## if you need to chage
#nav:
#  - ipynb:
#    - ch3: ch3.ipynb

theme: readthedocs

## mathjax for .md
markdown_extensions:
  - footnotes # 支援腳注
  - admonition # 支援提示區塊
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.6/MathJax.js?config=TeX-AMS-MML_HTMLorMML


plugins:
  - search
  - mkdocs-jupyter

關於 markdown_extensions 可以寫什麼，可以參考 Material for MkDocs - Python Markdown Extensions

Step 4. 上傳到 GITHUB

這邊可以用任何你知道的方法，把本機的資料夾上傳到 Github 上面。只需這一次就好。後面的步驟，都是在線上操作，基本上不需要碰到本機的資料夾。

• Github Desktop.

Step 5. 部署到 readthedocs

完成之後，只需要再做幾件事：

1. 把這個資料夾上傳到 Github 上面。
2. 登入 readthedocs，連結你的 github。選擇這個 repo，然後發佈即可。
3. 進入後的 NAME 要注意，他會變成這份文件網址的主要名稱。
4. 在部署選項上，記得要改成 MkDocs!!
5. 部署好，網址就會是 xxxxx.readthedocs.io/ 非常方便好記。

現在，一個簡單而基本可行的介面已經完成了！ 接下來只需要把你的 markdown 和 jupyter 檔案無腦放入 docs 資料夾中上傳即可！

Step 6.1. COLAB 使用方式

1. 在 google drive 開啟一個 colab 檔案。
2. 完成你的 md 或是 r, pyhton, julia 作業。
3. 選擇 File/Save a copy in Github, 接著選你要存放的 repo.
4. 這時候檔名前面記得要加 docs/ 因為要存到該 repo 的 docs 資料夾中。
5. 檔案命名方式，前面記得加上日期，例如 20250901_xxxxx.ipynb 這樣有利於 mkdocs 自動按日期順序排版。
6. 萬一有相同日期，就在後面加上數字，例如 2024021401, 2024021402, ...

Step 6.2. 當然也可以使用 GITHUB

github 的話，就是直接編輯 markdown 檔案。

Discussion

這套半自動寫作方案的核心概念是「降低進入門檻」。降低進入門檻的理由，並不完全是技術上的原因。如果要講步驟簡單，依賴工具少，那可能 Quarto 是更好的選擇。對我而言更重要的原因是有利於「原子習慣」的養成。 相較於 Quarto 需要完整的本機開發環境，這個方案只需要瀏覽器就能開始寫作。特別適合需要跨裝置工作、或是偶爾想修改幾個字但不想開啟重型軟體的情況。這樣簡單的方式有利於習慣建立。

當然，這個方案也有取捨。在客製化和進階功能上不如 Quarto 豐富，但對於大多數的學術寫作、筆記整理、或是簡單的技術文件來說已經足夠。重點是一旦設定完成，後續的發布流程幾乎是透明的——寫完就直接同步到網站上。

另一個意外的好處是版本控制。由於所有內容都在 GitHub 上，自然就有了完整的修改歷史記錄，這在傳統的文件編輯軟體中往往需要額外設定。

對於習慣用 Colab 做資料分析的研究者來說，這個方案讓寫作和分析可以在同一個環境中完成，減少了工具切換的成本。

See Also

• MkDcos
• Quarto
• readthedocs