跳轉到

1. 利用mkdocs部署靜態網頁至GitHub pages

Info

Material for MkDocs官方網站：MkDocs

推薦看下這個影片：
How to set up Material for MkDocs by @james-willett – 15m – Learn how to create and host a documentation site using Material for MkDocs on GitHub Pages in a step-by-step guide.

一、準備工作

1.下載Github Desktop

2.有一個GitHub賬號​​​​​​​(有手就行)

二、Creating your site

參考教程：

利用mkdocs部署靜態網頁至GitHubpages（更新版）

與其他教程不同，我首先建議先在Github建立一個名為你的名字+github.io的倉庫 img

img

然後開啟github Desktop 克隆到本地 img

img

img

開啟Wcowin.github.io目錄進入終端依次執行: 

1
2
pip install mkdocs-material
mkdocs new mkdocs-site
出現下圖的幾個檔案 img

docs檔案下是以後網站的內容，mkdocs.yml是配置檔案（配置主題，目錄，外掛等）

你在這個目錄下寫的任何東西都可以透過github Desktop 上傳到github上

執行下面的程式碼新增一個GitHub Workflow

過時的PublishMySite.yml

(執行下面的程式碼新增一個GitHub Workflow(已經過時但是仍然能用，最新方法見下方ci.yml)

1
2
3
4
5
mkdir .github
cd .github
mkdir workflows
cd workflows
vim PublishMySite.yml

在PublishMySite.yml裡面輸入以下內容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
name: publish site
on: # 在什麼時候觸發工作流
  push: # 在從本地main分支被push到GitHub倉庫時
    branches:
      - main
  pull_request: # 在main分支合併別人提的pr時
    branches:
      - main
jobs: # 工作流的具體內容
  deploy:
    runs-on: ubuntu-latest # 建立一個新的雲端虛擬機器 使用最新Ubuntu系統
    steps:
      - uses: actions/checkout@v2 # 先checkout到main分支
      - uses: actions/setup-python@v2 # 再安裝Python3和相關環境
        with:
          python-version: 3.x
      - run: pip install mkdocs-material # 使用pip包管理工具安裝mkdocs-material
      - run: mkdocs gh-deploy --force # 使用mkdocs-material部署gh-pages分支
)

1
2
3
4
5
mkdir .github
cd .github
mkdir workflows
cd workflows
vim ci.yml

.github/workflows/ci.yml，然後複製並貼上以下內容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
name: ci 
on:
  push:
    branches:
      - master 
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force

目錄樹狀圖: 

1
2
3
4
5
6
7
8
9
$ tree -a
.
├── .github
│   ├── .DS_Store
│   └── workflows
│       └── ci.yml
├── docs
│   └── index.md
└── mkdocs.yml

重點來了

倉庫setings/Actions/General 勾選這兩項

三、配置完善

開啟終端執行

pip install mkdocs-material

開啟**mkdocs.yml**

把以下的內容輸入進去（最簡單最基礎的配置） 

1
2
3
4
5
site_name: 網站名字
site_url: 網站連結
site_author: 你的名字
theme:
  name: material #主題

詳細mkdocs.yml配置見Changing the colors - Material for MkDocs

下次我會具體談談這個問題

在下方終端執行可以在瀏覽器看到實時網站 

1
mkdocs serve
img img

這個網站就算是初步建好了

最後去github Desktop上傳到github img

！！！重點
去倉庫的setings/pages選擇下圖示意的路徑

等待一會網址就出來了

你的網站網址就是：​

1
2
https://你github的名字.github.io/
因為我繫結了域名所以網址是：https://wcowin.work/
img

下次談談網站的mkdocs.yml具體配置1

  1. 於2023.3.24重寫此文 ↩