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

閱讀時間約 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


See Also


🎃

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

-客觀測量研究。 -應用統計。 -M is for Measurement.
留言0
查看全部
avatar-img
發表第一個留言支持創作者!
諸君: 今天來講:Ubuntu Desktop 22.04 LTS 半年來的使用心得。(2023-08-23)
今天來講:統計模擬研究的入門文章。(2023-08-23)
諸君: 今天來講:研究變項之間的關係設定。(2023-08-23)
諸君: 今天的主題是:「一週瀏覽器分頁」。(2023-08-23) 對很多人來說,一週的瀏覽器分頁,可能就像購物車清單一樣,是有點私密、而且能反映出一個人最近狀態的東西(當然不會全部列出來)。我覺得紀錄這件事能幫助我消滅一堆開著的分頁、而且能幫助我記下一些重要的思緒、或是文獻。所以我覺得可以嘗
介紹NIMBLE工具,自動抽樣貝氏計算。跨多平台,擴展BUGS語法,速度優於JAGS,尤其混合模型。受生態學家歡迎。參考Beraha等比較,詳閱Nimble用戶手冊及Bayesian分析資源。
諸君: 今天來講:Ubuntu Desktop 22.04 LTS 半年來的使用心得。(2023-08-23)
今天來講:統計模擬研究的入門文章。(2023-08-23)
諸君: 今天來講:研究變項之間的關係設定。(2023-08-23)
諸君: 今天的主題是:「一週瀏覽器分頁」。(2023-08-23) 對很多人來說,一週的瀏覽器分頁,可能就像購物車清單一樣,是有點私密、而且能反映出一個人最近狀態的東西(當然不會全部列出來)。我覺得紀錄這件事能幫助我消滅一堆開著的分頁、而且能幫助我記下一些重要的思緒、或是文獻。所以我覺得可以嘗
介紹NIMBLE工具,自動抽樣貝氏計算。跨多平台,擴展BUGS語法,速度優於JAGS,尤其混合模型。受生態學家歡迎。參考Beraha等比較,詳閱Nimble用戶手冊及Bayesian分析資源。
你可能也想看
Google News 追蹤
Thumbnail
這個秋,Chill 嗨嗨!穿搭美美去賞楓,裝備款款去露營⋯⋯你的秋天怎麼過?秋日 To Do List 等你分享! 秋季全站徵文,我們準備了五個創作主題,參賽還有機會獲得「火烤兩用鍋」,一起來看看如何參加吧~
Thumbnail
國泰CUBE App 整合外幣換匯、基金、證券等服務,提供簡便、低成本的美股定期定額投資解決方案。 5分鐘開戶、低投資門檻,幫助新手輕鬆進軍國際股市;提供人氣排行榜,讓投資人能夠掌握市場趨勢。
Thumbnail
從短篇文中教你認識會計之四大財務報表 在會計學當中,有固定之四大正式報表,分別為「資產負債表」、「綜合損益表」、「權益變動表」以及「現金流量表」,今天帶大家簡單認識會計當中的四大財務報表分別要帶給大家何種資訊價值。 資產負債表,又稱財務狀況表,從名字就可得知,其主要表達的資訊即一家公司在「某一時點」
以前教琴的時候,總是會讓學生回家練習多種速度,下次上課再指定當中某一速度。速度是音樂元素之一,以大區塊分有: 慢、中、快,每種大區塊之間又會分成很多小塊狀,而這樣多變的速度是讓個體練習 #聽覺區辨的好工具。 然而,只有速度適合作為聽覺區辨的工具嗎? 其實不然,除了構成音樂元素適合用來設計聽覺區辨活
注意力是可以省的,注意力也可以拿來對人生做投資,現在ru節省下來的可以創造出一股「注意力流」為自己的生命注入源源不絕的流水,創造人生的厚度
大家都怎麼用部落格做默默網路行銷的呢? 根據小妹我的觀察~ 可以分作商業跟非商業兩種(自己分的)   舉例來說~ 像是自己在部落格分享食記、分享一些好物使用心得、或經歷(就當生活紀錄分享) 然後透過網友的點閱、繼續分享,甚至長期以來成為粉絲~(默默地有了一點人氣⊙⊙) 其實像是上面這些分享,就可以作
Thumbnail
本文章目的是希望可以用最簡單的範例,來讓大家了解React到底是什麼東西,有什麼好處,並且套用bootstrap的navbar,加上自己客製的css,來達到component重用的目的! 用React來開發網頁,必須把目標拆解成一個個component,最後組合起來就成為一個網站! 假如我們目標是要
在自覺身體好一些後我又回到職場上,畢竟還是要為「五斗米折腰」。當然,心說真的「心理的傷口」倒底好了沒有我自己都不敢確定。也就這樣時好時壞的過了幾年,2014年,我在一家連鎖餐廳當行銷企劃,說來好笑,原本只是去應徵「美工設計」結果越做老闆越誇張一個人當N個人用,工作除了平面設計、行銷企劃、媒體公關、教
Thumbnail
與多數瀏覽器相同,Brave 同樣基於 Chromium,與 Chrome 有相同的核心。Brave 由 Javascript 創始人及 Mozilla 前 CTO 、共同創始人,Brendan Eich, 於 2015 年創立。
Thumbnail
SimplyBook.me 提供了豐富的客製功能,讓商家能更有彈性的打造專屬預約網站,當然,在選用客製功能時,您可能會遇到一些困難,接下來這篇文章,我們將分享如何使用 CSS 客製功能,調整網站顯示字型! SimplyBook.me 除了支援多種不同的客製功能外,也提供超過 15 個以上的範本,幫助
Thumbnail
在網路蓬勃發展的數位時代,大多數人都已習慣透過「搜尋」來找到「解答」,像是使用 Google 搜尋資料後,到店家的官網查看資訊,進而完成消費等。從另一個角度來看,如果經營者能因應搜尋引擎演算法的特性,將網站效益最大化,提昇搜尋結果排名,那無疑是增加更多曝光機會、觸及潛在客戶的最好選擇! 在先前分享
Thumbnail
在工作上,你都每年要訂工作目標以及執行方法了;在做產品時,你也會規畫產品的「road map」,而且一段時間就會檢視更新,那自己的人生,當然也需要定期檢視、思考這些問題。
Thumbnail
這個秋,Chill 嗨嗨!穿搭美美去賞楓,裝備款款去露營⋯⋯你的秋天怎麼過?秋日 To Do List 等你分享! 秋季全站徵文,我們準備了五個創作主題,參賽還有機會獲得「火烤兩用鍋」,一起來看看如何參加吧~
Thumbnail
國泰CUBE App 整合外幣換匯、基金、證券等服務,提供簡便、低成本的美股定期定額投資解決方案。 5分鐘開戶、低投資門檻,幫助新手輕鬆進軍國際股市;提供人氣排行榜,讓投資人能夠掌握市場趨勢。
Thumbnail
從短篇文中教你認識會計之四大財務報表 在會計學當中,有固定之四大正式報表,分別為「資產負債表」、「綜合損益表」、「權益變動表」以及「現金流量表」,今天帶大家簡單認識會計當中的四大財務報表分別要帶給大家何種資訊價值。 資產負債表,又稱財務狀況表,從名字就可得知,其主要表達的資訊即一家公司在「某一時點」
以前教琴的時候,總是會讓學生回家練習多種速度,下次上課再指定當中某一速度。速度是音樂元素之一,以大區塊分有: 慢、中、快,每種大區塊之間又會分成很多小塊狀,而這樣多變的速度是讓個體練習 #聽覺區辨的好工具。 然而,只有速度適合作為聽覺區辨的工具嗎? 其實不然,除了構成音樂元素適合用來設計聽覺區辨活
注意力是可以省的,注意力也可以拿來對人生做投資,現在ru節省下來的可以創造出一股「注意力流」為自己的生命注入源源不絕的流水,創造人生的厚度
大家都怎麼用部落格做默默網路行銷的呢? 根據小妹我的觀察~ 可以分作商業跟非商業兩種(自己分的)   舉例來說~ 像是自己在部落格分享食記、分享一些好物使用心得、或經歷(就當生活紀錄分享) 然後透過網友的點閱、繼續分享,甚至長期以來成為粉絲~(默默地有了一點人氣⊙⊙) 其實像是上面這些分享,就可以作
Thumbnail
本文章目的是希望可以用最簡單的範例,來讓大家了解React到底是什麼東西,有什麼好處,並且套用bootstrap的navbar,加上自己客製的css,來達到component重用的目的! 用React來開發網頁,必須把目標拆解成一個個component,最後組合起來就成為一個網站! 假如我們目標是要
在自覺身體好一些後我又回到職場上,畢竟還是要為「五斗米折腰」。當然,心說真的「心理的傷口」倒底好了沒有我自己都不敢確定。也就這樣時好時壞的過了幾年,2014年,我在一家連鎖餐廳當行銷企劃,說來好笑,原本只是去應徵「美工設計」結果越做老闆越誇張一個人當N個人用,工作除了平面設計、行銷企劃、媒體公關、教
Thumbnail
與多數瀏覽器相同,Brave 同樣基於 Chromium,與 Chrome 有相同的核心。Brave 由 Javascript 創始人及 Mozilla 前 CTO 、共同創始人,Brendan Eich, 於 2015 年創立。
Thumbnail
SimplyBook.me 提供了豐富的客製功能,讓商家能更有彈性的打造專屬預約網站,當然,在選用客製功能時,您可能會遇到一些困難,接下來這篇文章,我們將分享如何使用 CSS 客製功能,調整網站顯示字型! SimplyBook.me 除了支援多種不同的客製功能外,也提供超過 15 個以上的範本,幫助
Thumbnail
在網路蓬勃發展的數位時代,大多數人都已習慣透過「搜尋」來找到「解答」,像是使用 Google 搜尋資料後,到店家的官網查看資訊,進而完成消費等。從另一個角度來看,如果經營者能因應搜尋引擎演算法的特性,將網站效益最大化,提昇搜尋結果排名,那無疑是增加更多曝光機會、觸及潛在客戶的最好選擇! 在先前分享
Thumbnail
在工作上,你都每年要訂工作目標以及執行方法了;在做產品時,你也會規畫產品的「road map」,而且一段時間就會檢視更新,那自己的人生,當然也需要定期檢視、思考這些問題。