<!-- 事前先進入虛擬環境 -->
# 環境安裝
需要先進入想使用的虛擬環境內再開始以下步驟：
**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 為資料夾名稱
```markdown
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 %}
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet