MkDocs+Github搭建個人部落格

Elsy發表於2024-05-22
Github

寫在前面

在嘗試過Hugo、Jekyll等部落格框架後，我最終選擇了MkDocs+Github的方案，主要出於以下幾點考慮：

  1. 部落格內容可基於Markdown寫作，不需要掌握html等其它語法。

  2. 釋出簡單，只需幾個命令就可以部署好本地框架，更新也很方便。

  3. 頁面簡潔，可能對追求美觀的使用者而言還有提升空間，但對我完全足夠了。


本部落格所需基礎：
  • markdown語法
  • 命令列操作
  • python環境
  • github使用

什麼是MkDocs

MkDocs是一個靜態網站生成器，它專門為構建專案文件而設計。它的核心優勢在於速度、簡單性和美觀度。想象一下，你有一個專案，需要為它建立文件，而MkDocs能幫你輕鬆搞定這一切。

  • 官網地址：https://www.mkdocs.org/
  • 新手教程：https://www.mkdocs.org/getting-started/
  • 使用者手冊：https://www.mkdocs.org/user-guide/

搭建本地頁面

安裝

首先，請確保你的電腦已安裝python環境，之後就可以基於pip安裝mkdocs:

pip install mkdocs

接下來執行mkdocs --version確認安裝是否成功。

建立站點

執行以下命令：（dir_name可以自由命名）

mkdocs new dir_name

這行命令將會在當前目錄下建立一個新資料夾dir_name,資料夾中包括：

  • 子目錄docs: 部落格的核心內容（.md檔案）就包含在此目錄下
  • 配置檔案mkdocs.yml:暫時不用動它

然後進入dir_name資料夾，執行mkdocs serve，命令列中會顯示Serving on http://...,即可在本地訪問該站點。

配置檔案修改

可以透過編輯mkdocs.yml來修改頁面格式，示例如下：

site_name: Elsy's Blog
theme:
        name: readthedocs
nav:
        - 主頁: index.md     
        - 關於: aboutme.md

使用Github釋出線上網頁

  1. 在dir_name下執行mkdocs build,這會生成一個新資料夾site，其中包含了靜態站點的頁面內容。

  2. 在Github上新建一個倉庫。

  3. 將本地dir_name資料夾與Github新建倉庫連線。

  4. 在dir_name下執行mkdocs gh-deploy，成功執行後命令列會顯示"Your documentation should shortly be available at : ..."

網路不好時可能需要多執行幾次,而且很可能有點延遲2333

  1. 更新網頁：在本地docs資料夾下編輯完md文件後，命令列中執行mkdocs gh-deploy即可


版權宣告：本文采用知識共享 4.0 許可證 (署名-非商業性使用-禁止演繹)

相關文章