![CleanShot 2024-11-16 at 12.01.42@2x](https://hackmd.io/_uploads/BycqFcHf1g.png) # 如何用 MkDocs 製作個人網站部署在 github.io ## 簡介 [`MkDocs`](https://www.mkdocs.org/) 是一個快速、簡單、漂亮的靜態網站生成器，特別適合用來建立專案文件。本指南將介紹如何使用 Material for MkDocs 主題建立個人網站。 ## 基礎安裝 ```bash # 安裝 MkDocs 核心套件和 Material 主題 pip3 install mkdocs mkdocs-material # 建立新的 MkDocs 專案 # my-site 是專案名稱，可以自行更改 mkdocs new my-site cd my-site ``` ## 了解網頁建置的內容說明 下面是 `mkdocs.yml` 的範例，附帶詳細註解： 基本上 yml 這個檔案會是建立整個網頁內容結構，可以用來定義所要呈現的內容。 ```yaml # ===== 基本設置 ===== # 網站名稱，會顯示在瀏覽器標籤和導航列 site_name: Da-Wei # 網站 URL，通常是 GitHub Pages 的位址 site_url: https://dwhao84.github.io/ # 作者資訊 site_author: Da-Wei, Hao # 網站描述，用於 SEO site_description: Dawei's introduction # ===== 主題設置 ===== theme: # 使用 Material 主題 name: material # 設定語言為繁體中文 language: zh-Hant # 設定網站 logo（路徑相對於 docs 目錄） logo: assets/logo.png # 設定網站圖示 favicon: assets/square-code.png # ----- 功能設定 ----- features: # === 導航功能 === - navigation.tabs # 頂部顯示主要分類標籤 - navigation.sections # 側邊欄分區顯示 - navigation.expand # 自動展開導航項 - navigation.top # 顯示返回頂部按鈕 - navigation.footer # 顯示頁腳導航 - toc.follow # 目錄跟隨滾動 # === 搜尋功能 === - search.highlight # 搜尋結果高亮顯示 - search.share # 可分享搜尋結果 - search.suggest # 搜尋建議 # === 內容功能 === - content.code.copy # 程式碼區塊可複製 - content.tabs.link # 分頁內容可連結 # === 進階功能 === - navigation.tracking # 跟蹤導航位置 - navigation.instant # 即時頁面切換 - header.autohide # 滾動時自動隱藏頁首 - announce.dismiss # 可關閉公告 # ----- 配色方案 ----- palette: # === 亮色主題 === - media: "(prefers-color-scheme: light)" # 系統使用亮色模式時 scheme: default # 使用默認配色 primary: deep purple # 主要顏色 accent: purple # 強調顏色 toggle: icon: material/weather-sunny # 切換按鈕圖示 name: 切換至深色模式 # 切換按鈕提示文字 # === 暗色主題 === - media: "(prefers-color-scheme: dark)" # 系統使用暗色模式時 scheme: slate # 使用石板配色 primary: purple # 主要顏色 accent: deep purple # 強調顏色 toggle: icon: material/weather-night # 切換按鈕圖示 name: 切換至淺色模式 # 切換按鈕提示文字 ``` ## 網站結構說明 ```plaintext docs/ # 文件根目錄 ├── index.md # 首頁文件 ├── techstack.md # 技術棧介紹頁面 ├── work_experience/ # 工作經歷目錄 │ └── resume.md # 履歷文件 ├── projects/ # 專案作品目錄 │ └── Drink_Order_App.md # 專案介紹 └── contact.md # 聯絡方式頁面 ``` ## Navigation設置 ```yaml # 定義網站的導航結構 nav: - 首頁 / Home Page: index.md # 首頁連結 - 關於我 / About Me: # 關於我區段 - techstack.md # 技術棧頁面 - 工作經歷 / Working Experience: # 工作經歷區段 - work_experience/resume.md # 履歷頁面 - 專案作品 / Projects: # 專案作品區段 - projects/Drink_Order_App.md # 專案介紹頁面 - 聯絡方式 / Contact: contact.md # 聯絡方式頁面 ``` ## Markdown 擴展功能 由於網站的內容，都是用Markdown的方式來編寫，所以在編輯上有Markdown語法支援是蠻方便的是，下列是語法支援: ```yaml markdown_extensions: - tables # 支援表格功能 - attr_list # 支援屬性列表 - md_in_html # 支援在 HTML 中使用 Markdown - pymdownx.highlight: # 程式碼高亮 anchor_linenums: true # 行號錨點 - pymdownx.superfences # 支援高級圍欄程式碼區塊 - admonition # 支援提示區塊 - pymdownx.details # 支援可折疊區塊 - pymdownx.tabbed: # 支援分頁內容 alternate_style: true - footnotes # 支援腳註 - def_list # 支援定義列表 - pymdownx.tasklist: # 支援任務列表 custom_checkbox: true # 自定義核取方塊樣式 - toc: # 目錄設置 permalink: true # 顯示標題永久連結 - pymdownx.emoji: # Emoji 支援 emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg ``` ## 社群連結設置 ```yaml extra: social: # GitHub 連結 - icon: fontawesome/brands/github link: https://github.com/dwhao84 name: GitHub # Medium 連結 - icon: fontawesome/brands/medium link: https://medium.com/@dwsamurai84_dev name: Medium # Email 連結 - icon: fontawesome/solid/envelope link: mailto:dwsamurai84@gmail.com name: Email ``` ## 部署步驟 ```bash # 本地預覽：啟動開發伺服器 mkdocs serve # 部署至 GitHub Pages：自動建立並推送到 gh-pages 分支 mkdocs gh-deploy ``` ## 其他功能配置 ### Google Analytics ```yaml extra: analytics: provider: google property: !ENV GA_TRACKING_ID # 需要替換為實際的 GA 追蹤碼 ``` ### Cookie 提示 ```yaml extra: consent: title: Cookie 同意 # 提示標題 description: >- # 提示描述 我們使用 Cookie 來識別您的重覆訪問和偏好設定... ``` ### 插件優化 ```yaml plugins: - search # 搜尋功能 - tags # 標籤系統 - minify: # 最小化檔案 minify_html: true # 最小化 HTML minify_js: true # 最小化 JavaScript minify_css: true # 最小化 CSS ``` ## 注意事項 1. **資源文件**： - 確保所有圖片、圖示等資源文件放在 docs/assets/ 目錄下 - 檔案名稱建議使用英文，避免特殊字符 2. **開發流程**： - 修改配置後需要重新啟動 `mkdocs serve` - 建議先在local預覽確認無誤後再部署 3. **部署相關**： - 確保 GitHub 儲存庫已開啟 Pages 功能 - 部署時需要有網路連接 ## 常見問題解決 1. **部署失敗**： - 檢查 GitHub 儲存庫設定 - 確認有正確的提交權限 2. **套件相關**： - 使用 `pip3 list` 確認所有依賴都已安裝 - 可能需要更新套件版本 3. **語法問題**： - YAML 檔案對縮排敏感，使用空格而非 Tab - 確保所有冒號後面有空格 ## 參考資源 - [MkDocs 官方文件](https://www.mkdocs.org/) - [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) - [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) ## 如何放在 github.io 可以參考下列內容: [ 一分鐘在GitHub建立個人網站!](https://ithelp.ithome.com.tw/m/articles/10259505)
{"image":"https://hackmd.io/_uploads/r1rFtqSz1g.png","title":"如何用 MkDocs 製作個人網站部署在 github.io","description":"MkDocs 是一個快速、簡單、漂亮的靜態網站生成器，特別適合用來建立專案文件。本指南將介紹如何使用 Material for MkDocs 主題建立個人網站。","contributors":"[{\"id\":\"c5d773c7-162d-45c8-89bf-d22e2e85ae80\",\"add\":5695,\"del\":9}]"}
Expand menu