# 如何用 MkDocs 製作個人網站部署在 github.io

## 簡介
[`MkDocs`](https://www.mkdocs.org/) 是一個快速、簡單、漂亮的靜態網站生成器，特別適合用來建立專案文件。本指南將介紹如何使用 Material for MkDocs 主題建立個人網站。

## 基礎安裝

# 安裝 MkDocs 核心套件和 Material 主題
pip3 install mkdocs mkdocs-material

# 建立新的 MkDocs 專案
# my-site 是專案名稱，可以自行更改
mkdocs new my-site
cd my-site

## 了解網頁建置的內容說明

下面是 `mkdocs.yml` 的範例，附帶詳細註解：

基本上 yml 這個檔案會是建立整個網頁內容結構，可以用來定義所要呈現的內容。

# ===== 基本設置 =====
# 網站名稱，會顯示在瀏覽器標籤和導航列
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: 切換至淺色模式                  # 切換按鈕提示文字

## 網站結構說明

docs/                   # 文件根目錄
├── index.md           # 首頁文件
├── techstack.md       # 技術棧介紹頁面
├── work_experience/   # 工作經歷目錄
│   └── resume.md      # 履歷文件
├── projects/          # 專案作品目錄
│   └── Drink_Order_App.md  # 專案介紹
└── contact.md         # 聯絡方式頁面

## Navigation設置

# 定義網站的導航結構
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語法支援是蠻方便的是，下列是語法支援:

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

## 社群連結設置

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:[e-mail]
      name: Email

## 部署步驟

# 本地預覽：啟動開發伺服器
mkdocs serve

# 部署至 GitHub Pages：自動建立並推送到 gh-pages 分支
mkdocs gh-deploy

## 其他功能配置

### Google Analytics

extra:
  analytics:
    provider: google
    property: !ENV GA_TRACKING_ID  # 需要替換為實際的 GA 追蹤碼

### Cookie 提示

extra:
  consent:
    title: Cookie 同意              # 提示標題
    description: >-                # 提示描述
      我們使用 Cookie 來識別您的重覆訪問和偏好設定...

### 插件優化

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)