一分鐘快速了解【MkDocs + Material 主題】能幫你建立怎樣的文件網站。
以我的 DevOps 小學堂網站為例，錄製了一個短片，可以快速了解 MkDocs + Material 主題再搭配一些 plugins 能為你的文件網站提供哪些效果。
影片如下，或者可以到我的 Youtube 頻道觀看。
一點心得筆記：
還有一樣功能，我覺得也很直觀、好用：提供使用者切換文件的語言版本。需要的 plugin 是 mkdocs-static-i18n。
這裡說的不只是網站操作介面支援 i18n，而是能任意切換你寫的文件語言。當然前提是你得針對不同語言撰寫不同版本的文件。由於我的網站並未打算提供雙語版本，所以在影片中沒有展示這項功能，但我試過真的不錯。唯一可惜是卡在此 plugin 依賴的另一個元件 Lunr 尚未支援中文。只能等等看，或者自己改原始碼了。
另外，我還發現一些瓶頸：
- 中文搜尋。如前所述，問題一樣卡在外部依賴的元件 Lunr 不支援中文搜尋。
- 多版本的 API 文件，而且要讓使用者自由切換 API 版本。我嘗試的 plugin 是 MkDocs Material 官方文件裡面建議的 mike，但我並沒有成功，問題卡在 GitLab CI/CD 這關。後來爬文後發現，mike 的作者在某一個討論串裡面說他並不熟 GitLab，所以他的文件裡面也只展示了如何用在 GitHub 的 CI/CD pipeline。
要做到讓使用者任意切換版本的 API 文件並不容易，關於這個部分，我也許會找時間評估 Docusaurus 和 Hugo。
～先醬～
沒有留言: