Skip to content

Commit

Permalink
framework is done
Browse files Browse the repository at this point in the history
  • Loading branch information
root-hbx committed Jan 12, 2025
1 parent b65f1b3 commit a289c9f
Show file tree
Hide file tree
Showing 18 changed files with 130 additions and 97 deletions.
95 changes: 7 additions & 88 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,90 +1,9 @@
仓库模板
此仓库包含使用 mdBook 框架创建的书籍项目,演示了如何自动部署书籍到 GitHub Pages。
# XJTU-ICS Textbook

## 项目概览
This is the official website for XJTU-ICS textbook :wave:

本项目利用 mdBook,一个用于从 Markdown 文件创建现代在线书籍的工具。我们的目标是自动化构建和部署流程,以便每次更新内容时都能快速发布到 GitHub Pages 上。

## 如何使用

要在本地构建和预览书籍,请确保已安装 [Rust](https://www.rust-lang.org/) 和 mdBook。然后,克隆此仓库并运行以下命令:

```
clone https://github.com/your-username/your-repo-name.git
cd your-repo-name
mdbook serve
```

打开浏览器访问 `http://localhost:3000` 查看书籍。

## 自动部署流程

通过 GitHub Actions 实现了 CI/CD 流程,自动将书籍部署到 GitHub Pages。以下是部署流程的概述:

1. **推送更改**:将更改推送到 `main` 分支。
2. **GitHub Actions 触发**:基于 `.github/workflows/deploy.yml` 中定义的工作流程,GitHub Actions 会自动触发构建过程。
3. **构建书籍**:GitHub Actions 会安装 mdBook,然后构建书籍内容。
4. **部署到 GitHub Pages**:构建完成后,书籍会自动部署到 GitHub Pages。

你可以在 GitHub 仓库的 "Actions" 选项卡下查看工作流程的执行情况

### 关于Fork和GitHub Actions工作流

当你fork一个包含GitHub Actions工作流程文件的仓库时,工作流默认是不会自动运行的。这是为了防止恶意行为(比如自动运行可能消耗资源的工作流)。如果你想在fork的仓库中启用GitHub Actions工作流,你需要手动激活它们:

1. **前往你fork的仓库页面**,点击上方的`Actions`标签。
2. 如果工作流被禁用,你会看到一个消息提示你启用它们。点击`I understand my workflows, go ahead and enable them`按钮以激活工作流。
3. 启用GitHub Pages: 转到仓库设置中的“Pages”部分,启用GitHub Pages
4. 好吧,其实可以删掉.github文件夹直接在设置中的“Pages”部分,Build and deployment的Source选择GitHub Actions然后选择mdbook就好了。🆗

## 关于 mdBook

mdBook 是一个用 Rust 编写的命令行工具和库,用于从 Markdown 文件创建在线书籍。它灵感来源于 GitBook,并且专为编写技术文档和教程而设计。mdBook 生成的书籍具有清晰的结构、美观的界面,并且支持多种格式的输出,包括静态网站和 PDF 文件。

mdBook 提供了多种功能,如:

- **支持 Markdown**:使用 Markdown 编写内容,简单易用。
- **多语言支持**:可以轻松地创建多语言书籍。
- **可配置**:通过 `book.toml` 配置文件,你可以定制书籍的各个方面,如主题、插件和输出格式。
- **测试代码片段**:可以测试书籍中的代码片段,确保代码的准确性。
- **搜索功能**:生成的书籍带有内置的搜索功能,方便读者查找信息。

mdBook 非常适合创建如编程语言文档、软件使用手册和教程等技术文档。它的使用范围从个人项目到大型企业都非常广泛。

### 学习资源

要了解更多关于 mdBook 的信息,包括如何安装、使用和配置 mdBook,你可以访问以下资源:

- **GitHub 仓库**https://github.com/rust-lang/mdBook
- **官方文档**https://rust-lang.github.io/mdBook/

这些资源提供了丰富的指南和示例,帮助你开始使用 mdBook 来创建和发布你自己的在线书籍。

## 项目定制

本项目对 mdBook 进行了以下定制:

#### Black 主题

位于`theme\css\variables.css:62`

#### 自定义导航

位于`theme\index.hbs:180`

#### 修改CSS 效果

位于`theme\css\chrome.css`

如果你不需要这些定制,可以简单地通过以下操作进行调整或删除:

- **删除主题**:将 `theme` 文件夹从你的项目中删除,mdBook 将回退到默认主题。
- **修改主题和效果**:在 `theme` 文件夹中更改 CSS 和 hbs文件,你可以调整导航样式和其他视觉效果以满足你的需求。

## mdBook 目录生成工具

在本项目中还开发了一个小工具,用于从文件夹结构的一系列 Markdown 文件自动生成 `SUMMARY.md` 目录。简化从已有md文件生成书籍项目和目录结构的工作。

该工具的使用方法和源代码可以在下面的链接找到:

- [mdBook-tools GitHub 仓库](https://github.com/lzzsG/mdBook-generate-directory)
- [How to contribute](./ref-template.md)
- Acknowledgement
- [template](https://github.com/lzzsG/mdBook-pages-template)
- [mdBook Doc](https://rust-lang.github.io/mdBook/guide/creating.html)
- [CI for mdBook](https://github.com/rust-lang/mdBook/wiki/Automated-Deployment:-GitHub-Pages-(Deploy-from-branch))
92 changes: 92 additions & 0 deletions ref-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# 如何使用模板

仓库模板
此仓库包含使用 mdBook 框架创建的书籍项目,演示了如何自动部署书籍到 GitHub Pages。

## 项目概览

本项目利用 mdBook,一个用于从 Markdown 文件创建现代在线书籍的工具。我们的目标是自动化构建和部署流程,以便每次更新内容时都能快速发布到 GitHub Pages 上。

## 如何使用

要在本地构建和预览书籍,请确保已安装 [Rust](https://www.rust-lang.org/) 和 mdBook。然后,克隆此仓库并运行以下命令:

```
clone https://github.com/your-username/your-repo-name.git
cd your-repo-name
mdbook serve
```

打开浏览器访问 `http://localhost:3000` 查看书籍。

## 自动部署流程

通过 GitHub Actions 实现了 CI/CD 流程,自动将书籍部署到 GitHub Pages。以下是部署流程的概述:

1. **推送更改**:将更改推送到 `main` 分支。
2. **GitHub Actions 触发**:基于 `.github/workflows/deploy.yml` 中定义的工作流程,GitHub Actions 会自动触发构建过程。
3. **构建书籍**:GitHub Actions 会安装 mdBook,然后构建书籍内容。
4. **部署到 GitHub Pages**:构建完成后,书籍会自动部署到 GitHub Pages。

你可以在 GitHub 仓库的 "Actions" 选项卡下查看工作流程的执行情况

### 关于Fork和GitHub Actions工作流

当你fork一个包含GitHub Actions工作流程文件的仓库时,工作流默认是不会自动运行的。这是为了防止恶意行为(比如自动运行可能消耗资源的工作流)。如果你想在fork的仓库中启用GitHub Actions工作流,你需要手动激活它们:

1. **前往你fork的仓库页面**,点击上方的`Actions`标签。
2. 如果工作流被禁用,你会看到一个消息提示你启用它们。点击`I understand my workflows, go ahead and enable them`按钮以激活工作流。
3. 启用GitHub Pages: 转到仓库设置中的“Pages”部分,启用GitHub Pages
4. 好吧,其实可以删掉.github文件夹直接在设置中的“Pages”部分,Build and deployment的Source选择GitHub Actions然后选择mdbook就好了。🆗

## 关于 mdBook

mdBook 是一个用 Rust 编写的命令行工具和库,用于从 Markdown 文件创建在线书籍。它灵感来源于 GitBook,并且专为编写技术文档和教程而设计。mdBook 生成的书籍具有清晰的结构、美观的界面,并且支持多种格式的输出,包括静态网站和 PDF 文件。

mdBook 提供了多种功能,如:

- **支持 Markdown**:使用 Markdown 编写内容,简单易用。
- **多语言支持**:可以轻松地创建多语言书籍。
- **可配置**:通过 `book.toml` 配置文件,你可以定制书籍的各个方面,如主题、插件和输出格式。
- **测试代码片段**:可以测试书籍中的代码片段,确保代码的准确性。
- **搜索功能**:生成的书籍带有内置的搜索功能,方便读者查找信息。

mdBook 非常适合创建如编程语言文档、软件使用手册和教程等技术文档。它的使用范围从个人项目到大型企业都非常广泛。

### 学习资源

要了解更多关于 mdBook 的信息,包括如何安装、使用和配置 mdBook,你可以访问以下资源:

- **GitHub 仓库**https://github.com/rust-lang/mdBook
- **官方文档**https://rust-lang.github.io/mdBook/

这些资源提供了丰富的指南和示例,帮助你开始使用 mdBook 来创建和发布你自己的在线书籍。

## 项目定制

本项目对 mdBook 进行了以下定制:

#### Black 主题

位于`theme\css\variables.css:62`

#### 自定义导航

位于`theme\index.hbs:180`

#### 修改CSS 效果

位于`theme\css\chrome.css`

如果你不需要这些定制,可以简单地通过以下操作进行调整或删除:

- **删除主题**:将 `theme` 文件夹从你的项目中删除,mdBook 将回退到默认主题。
- **修改主题和效果**:在 `theme` 文件夹中更改 CSS 和 hbs文件,你可以调整导航样式和其他视觉效果以满足你的需求。

## mdBook 目录生成工具

在本项目中还开发了一个小工具,用于从文件夹结构的一系列 Markdown 文件自动生成 `SUMMARY.md` 目录。简化从已有md文件生成书籍项目和目录结构的工作。

该工具的使用方法和源代码可以在下面的链接找到:

- [mdBook-tools GitHub 仓库](https://github.com/lzzsG/mdBook-generate-directory)
30 changes: 21 additions & 9 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,28 @@

[Introduction](./misc/introduction.md)

----------
------

- [Part 1](./part1/README.md)
- [Chapter 1](./part1/ch1.md)
- [Chapter 2](./part1/ch2.md)
- [Part 2](./part2/README.md)
- [Chapter 1](./part2/ch1.md)
- [Chapter 2](./part2/ch2.md)
# Course Notes

----------
- [Part 1](./notes/part1/README.md)
- [Chapter 1](./notes/part1/ch1.md)
- [Chapter 2](./notes/part1/ch2.md)
- [Part 2](./notes/part2/README.md)
- [Chapter 1](./notes/part2/ch1.md)
- [Chapter 2](./notes/part2/ch2.md)

[Contributors](./misc/contributors.md)
# Labs Materials

- [ICS Labs](./labs/README.md)
- [Lab 0](./labs/lab0.md)
- [Lab 1](./labs/lab1.md)
- [Lab 2](./labs/lab2.md)
- [Lab 3](./labs/lab3.md)
- [Lab 4](./labs/lab4.md)
- [Lab 5](./labs/lab5.md)
- [Lab 6](./labs/lab6.md)

------

[Contributors](./misc/contributors.md)
1 change: 1 addition & 0 deletions src/labs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Lab Materials
2 changes: 2 additions & 0 deletions src/labs/lab0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Lab 0: How to Start

1 change: 1 addition & 0 deletions src/labs/lab1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Lab 1 Data Lab
1 change: 1 addition & 0 deletions src/labs/lab2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Lab 2: Bomb Lab
1 change: 1 addition & 0 deletions src/labs/lab3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Lab 3: Attack Lab
1 change: 1 addition & 0 deletions src/labs/lab4.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Lab 4: Cache Lab
1 change: 1 addition & 0 deletions src/labs/lab5.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Lab 5: Optimization Lab
1 change: 1 addition & 0 deletions src/labs/lab6.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Lab 6: Linker Lab
1 change: 1 addition & 0 deletions src/notes/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Course notes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

0 comments on commit a289c9f

Please sign in to comment.