<!-- 事前先進入虛擬環境 -->

# 環境安裝

需要先進入想使用的虛擬環境內再開始以下步驟：

**1. 安裝套件**

pip install mkdocs mkdocs-material

**2. 建立新的 MkDocs 專案**

SeaDeep 是專案名稱，可以自行更改

mkdocs new SeaDeep

**3. 移動到資料夾**

`docs` 資料夾在上一步會自動建立

cd .\SeaDeep\docs

**4. 放入要做成網站的檔案**

將 `.md` 檔案放置此處。

**5. mkdocs.yml 設置範例**

* usage、guide、reference 為資料夾名稱

nav:
  - 首頁: index.md
  - 安裝指南: install.md
  - 使用方法:
      - 基本: usage/basic.md
      - 進階: usage/advanced.md
  - 使用者指南:
      - 介紹: guide/intro.md
      - 小技巧: guide/tips.md
  - 參考資料:
      - API 文件: reference/api.md
      - 設定檔: reference/config.md

# 本地預覽

移動到專案資料夾

cd SeaDeep

在環境下於 `terminal` 輸入以下指令

mkdocs serve

使用以下網址打開瀏覽器

http://127.0.0.1:8000

# 部署到網路上

## 一、將所有檔案推到 Github

**1. 進入 MkDocs 專案資料夾**

cd SeaDeep

**2. 初始化 Git**

在專案根目錄 `SeaDeep/` 資料夾執行 `git` 指令。

git init

**3. 新增檔案、提交**

git add .
git commit -m "first commit"

**4. 連接 GitHub repo**

git branch -M main
git remote add origin https://github.com/你的帳號/倉庫名.git

**5. 推送到 GitHub**

git push -u origin main

## 二、部署網站到 GitHub Pages

**1. 使用 `MkDocs` 指令部署靜態網站**

GitHub 將會自動生成 HTML 放到 `gh-pages` 分支

mkdocs gh-deploy

看到這樣就完成了

To https://github.com/帳號/倉庫名.git
 * [new branch]      gh-pages -> gh-pages
INFO    -  Your documentation should shortly be available at: https://帳號.github.io/倉庫名/

**2. 到對應 GitHub repo 確認設定與網站連結**

設置：Settings → Pages


# 設定 GitHub Actions 自動部署

`GitHub Actions` 是 `GitHub` 提供的「**雲端自動化平台**」。它會在「雲端」建立一台臨時的虛擬電腦（runner），依照你的 `.yml` 設定檔，一步步執行你指定的命令。
可以用 `GitHub Actions` 讓網站自動建置，未來只需要執行 `push` ，不需要再執行 `mkdocs gh-deploy`。

## 1. 進入專案資料夾

cd SeaDeep

## 2. 建立多層資料夾

`GitHub Actions` 的系統會在每次 `push` 或觸發事件時，自動去 `.github/workflows` 路徑搜尋是否有 `.yml` 需要執行。

mkdir -p .github/workflows

## 3. 建立檔案

可直接於先前創建的 `workflows` 資料夾內手動建立 `deploy.yml`，或於 `Git Bash` 中輸入以下指令。

touch .github/workflows/deploy.yml

## 4. 撰寫 `deploy.yml` 內容

GitHub Actions 啟動
        ↓
雲端建立 Ubuntu 環境
        ↓
使用 actions/checkout → 下載你的 repo
        ↓
使用 actions/setup-python → 安裝 Python
        ↓
run: pip install mkdocs mkdocs-material → 安裝套件
        ↓
run: mkdocs build → 建置網站內容（將 Markdown 文件轉換為靜態網站）
        ↓
uses: peaceiris/actions-gh-pages@v3 → 部署到 gh-pages 分支
        ↓
GitHub Pages 顯示最新網站 🎉

### （1） 自訂工作流程名稱

這是「工作流程（Workflow）」的名稱。它會顯示在 `GitHub` 專案頁面的「Actions」分頁裡。

name: 自動部署 Mkdocs 網站

### （2） 設定觸發條件

當有人對 `main` 分支執行 `git push` 時，觸發這個 workflow。

on:                       
  push:
    branches:
      - main              

### （3） 定義要執行的工作環境

* `jobs` 是要執行的工作們。
* `deploy:` 是工作名稱（可自訂，如：`build`、`publish` 等）
* `runs-on:` 表示在哪個雲端主機執行
* `GitHub Actions` 是跑在它的雲端環境，與本機端無關，所以通常使用相容性最好的 `ubuntu-latest`。

jobs:                     
  deploy:                 
    runs-on: ubuntu-latest 

### （4） 定義每個工作下每個步驟該做什麼

**Step 1**
把程式碼從 `GitHub` 下載到雲端的工作環境
這是**固定寫法**，幾乎所有 workflow 都需要。
* `uses:作者/模組名稱@版本`：呼叫由該作者製作的 `Action` 模組

    steps:                
      - name: Checkout repository
        uses: actions/checkout@v3 

**Step ２**

在雲端環境中安裝 Python，版本使用最新的 3.x。
因為 `MkDocs` 是 Python 套件，必須先安裝 Python。

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: 3.x

**Step ３**

執行命令 `pip install` 安裝 `Mkdocs` 套件。

      - name: Install dependencies（相依套件）
        run: pip install mkdocs mkdocs-material

**Step ４**

執行 `mkdocs build`，把 `Markdown` 轉成 HTML 靜態檔案（編譯）

      - name: Build site
        run: mkdocs build

**Step 5**

使用 `GitHub` 內建 `GITHUB_TOKEN`，可自動授權推送至 `gh-pages` 分支。

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }} # GITHUB_TOKEN
          publish_dir: ./site                   # mkdocs build 生成的資料夾
          commit_message: "Auto deploy site from GitHub Actions"

### `deploy.yml` 完整程式碼

name: Deploy MkDocs site   # ① 工作流程名稱，可自訂

on:                       # ② 觸發條件
  push:
    branches:
      - main              # 監控 main 分支的 push

jobs:                     # ③ 定義要執行的工作
  deploy:                 # 工作名稱，可自訂
    runs-on: ubuntu-latest # 在哪個環境執行（固定格式）
    steps:                # ④ 每個步驟要執行什麼
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: 3.x

      - name: Install dependencies
        run: pip install mkdocs mkdocs-material

      - name: Build site
        run: mkdocs build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }} 
          publish_dir: ./site
          commit_message: "Auto deploy site from GitHub Actions"

部署後，未來只要 `push` 到 `main`，`GitHub Actions` 便會自動執行指令，讓網站自動同步更新。

### 補充

* 自己執行指令 → 用 `run:`
* 呼叫別人寫好的 Action 模組 → 用 `uses:`

## 5. 上傳至 GitHub

git add .
git commit -m "Add GitHub Actions for Mkdocs auto deploy"
git push

## 6. 確認是否成功執行

點擊 Actions



# 錯誤訊息

## 1. 破圖
圖片不在 `docs/` 裡，MkDocs 不會自動把 `docs/` 以外的檔案複製到網站中，圖片在建置時找不到，才會出現破圖。


**解法:**
把圖片移到 `docs/picture` 資料夾內。

## 2. 執行 GitHub Actions 自動部署權限不足

### 查看錯誤訊息
1. 去倉庫的 `actions` 裡面看
2. 查看 `workflows` 紀錄
3. 點進去看
4. 再點你 `jobs` 下面自訂的那個工作名稱 `deploy` 看錯誤訊息
5. 權限問題如下

remote: {"auth_status":"access_denied_to_user","body":"Permission to WenChunPan/SeaDeep_UserManual.git denied to github-actions[bot]."}
fatal: unable to access 'https://github.com/WenChunPan/SeaDeep_UserManual/': The requested URL returned error: 403

403 → 權限拒絕（Forbidden）

`GitHub Actions` 沒有權限 `push` 到你的 `repository` 的 `gh-pages` 分支。

### 解決方法

改用 `peaceiris/actions-gh-pages`，並使用 `GitHub` 內建 `GITHUB_TOKEN`，可自動授權推送至 `gh-pages` 分支。

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }} # GITHUB_TOKEN
          publish_dir: ./site                   # mkdocs build 生成的資料夾
          commit_message: "Auto deploy site from GitHub Actions"

# Resource

{%preview https://hackmd.io/cNmSPyWlTqGaQdX8eKCZew %}