构建 CI/CD 实现自动化静态网站部署

每次 Push 或 PR 到 main 分支都触发。详情见README.md

Author: H-Sofie

.github/workflows/deploy.yml

@@ -0,0 +1,32 @@
+name: Deploy MkDocs
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@main
+
+      - name: Setup Python
+        uses: actions/setup-python@main
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material
+
+      - name: Update dir
+        run: python ./update_dir.py
+
+      - name: Deploy docs to GitHub Pages
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,27 +1,27 @@
-![avatar](https://raw.githubusercontent.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/main/image/cqut_logo.png)
+![avatar](https://cdn.jsdmirror.com/gh/Royfor12/CQUT-Course-Guide-Sharing-Scheme/image/cqut_logo.png)
 
 # 💡 课程攻略共享计划
 
-[![](https://img.shields.io/github/watchers/Royfor12/CQUT-electronic-information-engineering.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/watchers)
-[![](https://img.shields.io/github/stars/Royfor12/CQUT-electronic-information-engineering.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/stargazers)
-[![](https://img.shields.io/github/forks/Royfor12/CQUT-electronic-information-engineering.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/network/members)
-[![](https://img.shields.io/github/issues-pr-closed-raw/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-electronic-information-engineering/issues)
+[![](https://img.shields.io/github/watchers/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/watchers)
+[![](https://img.shields.io/github/stars/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/stargazers)
+[![](https://img.shields.io/github/forks/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/forks)
+[![](https://img.shields.io/github/issues-pr-closed-raw/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme/pulls)
 ![](https://img.shields.io/github/repo-size/Royfor12/CQUT-Course-Guide-Sharing-Scheme.svg?style=flat)
-![Platform](https://img.shields.io/badge/platform-windows%20|%20linux%20|%20macos-green.svg)
+[![jsdelivr](https://img.shields.io/badge/CDN-jsdelivr-brightgreen?logo=jsdelivr&logoSize=auto)](https://www.jsdelivr.com/)
 
 ## ❗ 写在最前
 
-如果你打开本网页不知如何操作或检索所需的资源，请先点击[GitHub使用指南](https://www.bilibili.com/video/BV1hS4y1S7wL)。
+如果你打开本网页不知如何操作或检索所需的资源，请先点击[GitHub使用指南](https://www.bilibili.com/video/BV1hS4y1S7wL)。  
 旧版备份[2025/1/7](https://pan.baidu.com/s/1_YFOqR_eSd8bXokEGMCrbg?pwd=hq33)提取码：hq33
 
 ## ⚡ 前言
 
-网络冲浪🏄时发现了：浙江大学的课程攻略共享计划与上海交通大学生存手册，深受震撼。\
+网络冲浪🏄时发现了：浙江大学的课程攻略共享计划与上海交通大学生存手册，深受震撼。  
 故此也想建立一个重庆理工大学课程攻略计划，本仓库的内容包括重庆理工大学的各类课程复习资料。本仓库为非营利、永久免费的开源项目，仓库之目的即推动知识传播、提高资源质量、减少获取成本、提倡无纸化资料、促进教育公平，让西唯兵学子在备考、复习之时不必再苦寻资料。
 
-我们同在重庆理工大学，以相同的身份，学习相同的课程，师从相同的教授。教授们往往为了省事，所以几年的课程资料、期末试题可能变化不大。学习这些资料，阅读学长学姐留下的复习攻略，可能会减轻信息不对称对你造成的影响，让你在复习时更有针对性。面对年复一年、无数学子独立摸索、重复劳动的现状，我不禁感到惋惜与不平。\
-再加之本人有数字仓鼠🐹症。
-因此，我希望建立一个项目，将这些隐匿的、不确定性的、口耳相传的知识资源整合起来，使之变得公开透明、易于获取，并且能够由大家共同维护、持续丰富。
+我们同在重庆理工大学，以相同的身份，学习相同的课程，师从相同的教授。教授们往往为了省事，所以几年的课程资料、期末试题可能变化不大。学习这些资料，阅读学长学姐留下的复习攻略，可能会减轻信息不对称对你造成的影响，让你在复习时更有针对性。面对年复一年、无数学子独立摸索、重复劳动的现状，我不禁感到惋惜与不平。  
+再加之本人有数字仓鼠🐹症。  
+因此，我希望建立一个项目，将这些隐匿的、不确定性的、口耳相传的知识资源整合起来，使之变得公开透明、易于获取，并且能够由大家共同维护、持续丰富。  
 借用浙大的课程攻略中的一句话：**我希望只要是前人走过的弯路，后人就不必再走。这是我的信念，也是我建立这个项目的原因。**
 
 ## 📣 特性
@@ -39,6 +39,12 @@
 
 目前涵盖的科目还很少，欢迎各位前来PR！
 
+### 🎉 新界面
+
+本仓库已实现 GitHub Actions 工作流全自动部署。  
+在 Push 或 PR 后会触发自动构建新的静态网页并部署到 **https://Royfor12.github.io/CQUT-Course-Guide-Sharing-Scheme** 。  
+该网页界面友好，在左侧导航栏中可以查找并单独下载指定文件。
+
 ## 🦧 平台
 
 以下摘录自浙江大学课程攻略共享计划
@@ -51,10 +57,9 @@
 
 ## ⏬ 下载
 
-我们在这里介绍两种下载文件的方式：
-
 1. 你当然可以克隆或者下载整个项目，但因为整个项目较大，可能对于一部分人不太方便。这里对于使用Chrome和Firefox的用户，我们推荐一个[Chrome插件](https://chrome.google.com/webstore/detail/gitzip-for-github/ffabmkklhbepgcgfonabamgnfafbdlkn?hl=en)和[Firefox插件](https://addons.mozilla.org/en-US/firefox/addon/gitzip/)，**GitZip**。该插件可以让我们只下载项目中我们感兴趣的那些文件夹，也就是我们所感兴趣的课程的资料。同时对Opera用户来说，大部分的Chrome插件都可以通过一款名为[Install Chrome Extensions](https://addons.opera.com/zh-cn/extensions/details/install-chrome-extensions/)的Opera插件安装使用，GitZip也不例外。而对于使用其他浏览器的朋友来说，很遗憾，这个插件暂时只能在这三款浏览器中使用。
-2. 或者复制该文件夹的网址，粘贴入[DownGit](https://minhaskamal.github.io/DownGit/#/home)中，选择**download**即可。
+2. 或者复制想要打包下载文件夹的网址，粘贴入[DownGit](https://minhaskamal.github.io/DownGit/#/home)中，选择**download**即可。
+3. 访问 **https://Royfor12.github.io/CQUT-Course-Guide-Sharing-Scheme** 。文件下载加速CDN由 [![jsdelivr](https://img.shields.io/badge/CDN-jsdelivr-brightgreen?logo=jsdelivr&logoSize=auto)](https://www.jsdelivr.com/) 及其镜像站提供。
 
 注：对于第一种方法而言，它需要使用者拥有github账号，并且该插件需要使用者的授权；而第二种方法虽然一次只能下载一个文件夹，但它并不需要使用者拥有github账号。
 
@@ -166,7 +171,7 @@ Issue、PR、纠错、补充、上传攻略，完全欢迎！
 
 ## 📔待办事项
 - [ ] 制定使用指南
-- [ ] 设计一个网页便于检索与预览
+- [x] 设计一个网页便于检索与预览
 
 ## 🍻赞助
 Buy me coffee.
@@ -179,4 +184,4 @@ Buy me coffee.
 
 ## ✨Stars
 
-[![Star History Chart](https://api.star-history.com/svg?repos=Royfor12/CQUT-Course-Guide-Sharing-Scheme&type=Date)](https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme&Date)
+[![Star History Chart](https://api.star-history.com/svg?repos=Royfor12/CQUT-Course-Guide-Sharing-Scheme&type=Date)](https://star-history.com/#Royfor12/CQUT-Course-Guide-Sharing-Scheme&Date)

mkdocs.yml

@@ -0,0 +1,42 @@
+site_name: 重庆理工大学课程攻略共享计划
+site_author: H·Sofie, Royfor12
+site_description: 使用MKDocs构建的静态网页
+site_url: https://Royfor12.github.io/CQUT-Course-Guide-Sharing-Scheme
+repo_url: https://github.com/Royfor12/CQUT-Course-Guide-Sharing-Scheme
+
+theme:
+  name: material
+  language: zh
+  font:
+    text: Noto Sans Simplified Chinese
+  features:
+    - navigation.instant # 即时加载
+    - navigation.instant.prefetch # 即时预取
+    - navigation.instant.progress # 加载进度指示器
+    - navigation.instant.preview # 即时预览
+    - navigation.sections # 导航栏分组
+    - navigation.path # 标题导航路径
+    - navigation.top # 返回顶部按钮
+    - toc.follow # 目录锚点跟随
+    - search.highlight # 搜索高亮显示
+    - content.footnote.tooltips # 脚注内联
+
+plugins:
+  - search:
+      lang: zh
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - pymdownx.betterem
+  - pymdownx.caret
+  - pymdownx.mark
+  - pymdownx.tilde
+  - pymdownx.tasklist:
+      custom_checkbox: true

update_dir.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import os
+import shutil
+from urllib.parse import quote
+
+# 从 GitHub Actions 环境变量里获取仓库所有者和仓库名、分支名
+repo_full = os.environ.get("GITHUB_REPOSITORY", "defaultOwner/defaultRepo")
+branch = os.environ.get("GITHUB_REF_NAME", "main")
+
+# 文本文件走 blob 链接（在线查看），二进制文件走 cdn 链接（便于直接下载）
+BLOB_URL_PREFIX = f"https://github.com/{repo_full}/blob/{branch}/"
+BIN_URL_PREFIX = f"https://cdn.jsdmirror.com/gh/{repo_full}/"
+
+# 顶层排除目录
+EXCLUDE_TOP_DIRS = {'.git', 'docs', '.vscode', '.circleci', 'site', 'image'}
+
+# 视为 README 的文件名
+README_CANDIDATES = {'README.md', 'readme.md', 'index.md'}
+
+# 生成 blob 链接
+BLOB_EXTS = {'md', 'txt', 'c', 'cpp', 'py'}
+
+def process_directory(base_dir: str, rel_path: str):
+    """
+    将 base_dir(绝对路径) 对应的目录内容，递归生成到 docs/rel_path 目录下的 index.md 中。
+    1. 若有 README_CANDIDATES 中任意文件，则将其内容原样写入。
+    2. 新起一行后，输出大标题 "# 文件列表"。
+    3. 列出当前目录所有文件的链接（md/txt -> blob，其它 -> cdn）。
+    4. 对各子文件夹，递归调用 process_directory，生成各自的 docs/rel_path/subfolder/index.md。
+    """
+
+    # 在 docs/ 下创建与原目录相同层级的文件夹
+    docs_folder = os.path.join("docs", rel_path)
+    if not os.path.exists(docs_folder):
+        os.makedirs(docs_folder)
+
+    items = sorted(os.listdir(base_dir))
+
+    # 尝试找到任意一个 README
+    readme_content = ""
+    for candidate in README_CANDIDATES:
+        if candidate in items:
+            readme_path = os.path.join(base_dir, candidate)
+            with open(readme_path, "r", encoding="utf-8") as rf:
+                readme_content = rf.read()
+            break  # 找到一个就可以退出
+
+    # 收集文件链接列表
+    file_links = []
+    subdirs = []
+    for item in items:
+        full_item_path = os.path.join(base_dir, item)
+        if os.path.isfile(full_item_path):
+            # 若是 README，则已处理过；否则纳入链接
+            if item not in README_CANDIDATES:
+                ext = item.split(".")[-1].lower() if "." in item else ""
+                # 判断用 blob 还是 cdn 加速
+                if ext in BLOB_EXTS:
+                    file_url = BLOB_URL_PREFIX + quote(f"{rel_path}/{item}")
+                else:
+                    file_url = BIN_URL_PREFIX + quote(f"{rel_path}/{item}")
+                file_links.append((item, file_url))
+        else:
+            # 是子目录
+            subdirs.append(item)
+
+    # 写出当前目录的 index.md
+    index_md_path = os.path.join(docs_folder, "index.md")
+    with open(index_md_path, "w", encoding="utf-8") as wf:
+        # 1) 写 README 内容（若有）
+        if readme_content.strip():
+            wf.write(readme_content.strip())
+            wf.write("\n\n---\n\n")  # 加点空行，避免直接跟标题混在一起
+
+        # 2) 输出大标题“# 文件列表”
+        wf.write("# 文件列表\n")
+
+        # 3) 列出当前目录内的文件链接
+        for fname, url in file_links:
+            wf.write(f"- [{fname}]({url})\n")
+        wf.write("\n")
+
+    # 4) 递归处理子目录
+    for subdir in subdirs:
+        sub_rel_path = os.path.join(rel_path, subdir)
+        full_subdir_path = os.path.join(base_dir, subdir)
+        process_directory(full_subdir_path, sub_rel_path)
+
+
+if __name__ == "__main__":
+
+    # 确保 docs 目录存在
+    if not os.path.exists("docs"):
+        os.mkdir("docs")
+
+    # 排除 EXCLUDE_TOP_DIRS
+    top_dirs = []
+    for d in sorted(os.listdir(".")):
+        if os.path.isdir(d) and d not in EXCLUDE_TOP_DIRS:
+            top_dirs.append(d)
+
+    for d in top_dirs:
+        # 绝对路径
+        abs_path = os.path.abspath(d)
+        # rel_path 就是顶层目录的名字 d
+        process_directory(abs_path, d)
+
+    # 若仓库根目录下存在 README.md，则复制到 docs/index.md 当主页
+    if os.path.exists("README.md"):
+        shutil.copyfile("README.md", "docs/index.md")