Github仓库作为母仓库的子模块⚓︎

约 978 个字 49 行代码预计阅读时间 6 分钟

我的docs\notes\文件夹是git的一个子仓库（本地E:\Study\College Lessons对应github的College-Notes仓库，远程拉取college notes仓库后在D:\Program Files\Github\Muchili-code.github.io创建一个仓库，将College-Notes仓库作为D:\Program Files\Github\Muchili-code.github.io\docs\notes子文件夹）

现在有两个 GitHub 仓库：

Muchili-code.github.io (主页网站，目前由 D:\Program Files\Github\muchili-code.github.io 管理，使用 MkDocs)
College-Notes (学习笔记，目前由 E:\Study\College Lessons 管理)

Git 子模块 允许我们将一个 Git 仓库（College-Notes）作为另一个 Git 仓库（Muchili-code.github.io）的子目录。这样，笔记源文件 (E:\Study\College Lessons) 可以保持独立，但主页网站可以引用并显示它们。

重要提示： 这个方法需要配置 GitHub Actions 来正确部署包含子模块的 MkDocs 网站，因为 GitHub Pages 的默认构建流程不会自动克隆子模块。

包含 MkDocs 源文件⚓︎

确认子仓库包含 MkDocs 源文件。确保 E:\Study\College Lessons 这个本地目录（即 College-Notes 远程仓库的本地存储位置）已经包含了 MkDocs 所需的 docs 文件夹和 mkdocs.yml 文件。这确保让 College-Notes 这个仓库自身能够被 MkDocs 构建成一个网站。
如果还没有在E:\Study\College Lessons 目录下设置 mkdocs.yml

导航到 E:\Study\College Lessons，编辑 mkdocs.yml

YAML
 # E:\Study\College Lessons\mkdocs.yml

site_name: 我的大学学习笔记  # 你不需要在这里设置 site_url，因为它将作为主网站的一部分
# 假设你的笔记 Markdown 文件直接在 College Lessons 根目录下  
docs_dir: . 

nav:  
  - 简介: README.md # 确保你有 README.md 作为主页  
  - 大学一: College 1/index.md # 示例，你需要根据实际文件调整路径  
  - 大学二: College 2/index.md  
  # ... 添加所有你的笔记目录和文件

theme:  
  name: material  
  features:  
    - navigation.tabs

提交这些更改并推送到 College-Notes 远程仓库：

PowerShell
cd "E:\Study\College Lessons"  
git add mkdocs.yml  
git commit -m "Add MkDocs config to College-Notes"  
git push origin main

添加子模块⚓︎

打开 PowerShell 或 Git Bash。导航到主页仓库 Muchili-code.github.io 的根目录：

PowerShell
1	`cd "D:\Program Files\Github\muchili-code.github.io"`

添加 College-Notes 作为子模块：
将其 College-Notes添加到 docs 目录下的一个子文件夹，例如 notes。这样，笔记网站的内容将在主站的 docs/notes/路径下访问。

PowerShell
git submodule add https://github.com/Muchili-code/College-Notes.git docs/notes

这将把 College-Notes 仓库克隆到 D:\Program Files\Github\muchili-code.github.io\docs\notes\ 目录下。
同时，它会在你的 .gitmodules 文件中添加一个条目，并在你的 muchili-code.github.io 仓库中创建一个指向子模块的特殊 Git 对象。
提交子模块的更改：
Git 会自动将 .gitmodules 文件和子模块的引用添加到暂存区。

PowerShell
git commit -m "Add College-Notes as a submodule under docs/notes"

4. 推送到远程仓库：

PowerShell
git push origin main

配置原仓库⚓︎

现在你需要告诉你的主网站 MkDocs 如何在导航中包含子模块的内容。

编辑 D:\Program Files\Github\muchili-code.github.io\mkdocs.yml 文件。
在 nav 部分添加一个条目来指向你的笔记子模块：

YAML
# D:\Program Files\Github\muchili-code.github.io\mkdocs.yml


site_name: 我的个人主页  
site_url: https://Muchili-code.github.io/

nav:  
  - 主页: index.md  
  - 关于我: about.md # 如果你有其他页面  
  - 我的学习笔记: !include docs/notes/mkdocs.yml # 这里是关键！指示 MkDocs 在构建你的主网站时，去读取 docs/notes/ 目录下的 mkdocs.yml 文件，并将其 nav 部分的内容整合到主网站的导航中。它会以 docs/notes/ 作为基础路径来解析子模块中的 Markdown 文件路径。    
  # MkDocs Material 主题支持 \!include 语法来引入另一个 mkdocs.yml 的导航结构

theme:  
  name: material  
  features:  
    - navigation.tabs  
    # ... 其他主题设置

提交这些更改并推送到远程仓库：

PowerShell
cd "D:\Program Files\Github\muchili-code.github.io"  
git add mkdocs.yml  
git commit -m "Update mkdocs.yml to include College-Notes submodule"  
git push origin main

配置 GitHub Actions 工作流⚓︎

这是最关键的一步，因为默认的 GitHub Pages 构建不会克隆子模块。你需要为 Muchili-code.github.io 仓库添加一个 GitHub Actions 工作流。

在 D:\Program Files\Github\muchili-code.github.io 目录下创建以下文件夹结构：
.github/workflows/
在 D:\Program Files\Github\muchili-code.github.io\.github\workflows\ 目录下创建一个新的 YAML 文件，例如 deploy.yml。
编辑 deploy.yml 文件
提交并推送这个新的工作流文件：

PowerShell
cd "D:\Program Files\Github\muchili-code.github.io"  
git add .github/workflows/deploy.yml  
git commit -m "Add GitHub Actions workflow for submodule deployment"  
git push origin main

验证部署⚓︎

检查 GitHub Actions 运行：
登录 GitHub.com，进入 Muchili-code.github.io 仓库。
点击顶部导航栏的 "Actions" (动作)。
你应该能看到一个名为 "Deploy Docs with Submodules" 的工作流正在运行或已完成。如果它失败了，点击它查看日志以获取错误详情。
访问你的网站：
成功运行后，访问 https://Muchili-code.github.io/。
你的导航栏应该出现一个指向“我的学习笔记”的条目。点击它，你应该能看到 College-Notes 仓库中的内容被加载到主网站中。

这个过程相对复杂，特别是在 GitHub Actions 配置部分。请务必仔细按照每个步骤操作。如果在任何步骤遇到问题，请提供详细的错误信息，我会尽力帮助你排查。

更新主仓库的子模块⚓︎

更新子模块本地目录的远程仓库
运行git submodule update --remote，拉取子模块远程仓库的最新更新存入子模块的本地目录
更新本地母仓库的远程仓库中的子模块部分