基于Github Pages部署mdBook课程主页

一份开箱即用、自顶向下的mdBook部署指南

在这之前我们提到了基于Github Pages服务部署MkDocs网页的步骤，这里我们会讲解如何基于Github Actions部署mdBook网页。

我们会提及：

• mdBook 和 MkDocs 的使用场景
• 如何利用GitHub Actions部署mdBook主页
• 一键部署（白嫖专属）

参考文档：

• mdBook Documentation
• CI for mdBook
• mdBook script ref
• recommended plugins for mdBook
• lzzsG's mdBook template

如何选择mdBook或MkDocs

• MkDocs
• mdBook

笔者认为 mdBook是MkDocs的子集，mdBook更加简明扼要，MkDocs扩展性更强。

如果是部署某个课程的Textbook，我推荐使用mdBook (参考 xjtu-ics textbook)；

如果是部署个人博客/某个学科的多个课程集合 (本网站就是最好的体现)，更推荐使用MkDocs。

如何利用Github Action部署mdBook

这里我们不走官网提供的流程，因为它会涉及到本地与远端的不同处理。

我的方案能够保证开箱即用，本地和远程都 work well :))

本地环境部署

配置rust环境

这里以MacOS使用homebrew为例：

brew install rust

安装时间比较长，10min左右，如此会安装好rust全家桶，包括 rust / cargo ...

安装mdBook

cargo install mdbook

远端框架部署

Detailed info

根据模板创建repo

来到：mkdocs template

选择右上角 Use this template > Create a new repository

如此就创建好远端的全部内容了！

本地调试与客制化

要在本地构建和预览书籍，请确保已安装 Rust 和 mdBook。然后，克隆上述根据模板新建的仓库(xxx)并运行以下命令：

git 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（deploy.yml中设置了这个操作），然后构建书籍内容
4. 部署到 GitHub Pages：构建完成后，书籍会自动部署到 GitHub Pages
5. 现在可以在 GitHub 仓库的 "Actions" 选项卡下查看工作流程的执行情况

是不是看的很迷？其实你什么都不用做，上述根据template走的内容已经把上述神奇的Actions流程全部包含了

此时你会发现在settings > Code and automation > Pages中，显示已经可以visit这个website了：

从某种程度上来说，这个教程已经可以完结撒花了🎉

但是我们还没有结束🤡

客制化插件与对应CI修改

我自己的配置是参考这个教程来的。

它其中提及了三个插件，但是我在本地和远端都只对HINT这个插件有需求，因此这里介绍如何配置它：

HINT Plugin

在gitbook中，可以使用hint来实现一些提示块，在mdbook中，同样也有类似的插件实现这一功能，mdbook-admonish：

仓库链接：https://github.com/tommilligan/mdbook-admonish

本地安装

省流：看这里

现在你在本地运行mdbook serve就可以看见对应的模块渲染了

CI配置

根据上述，我们非常心满意足，于是我们会git push origin main

但是此时git push 会发现报错！

原因是：CI的本质是将mdbook部署在github提供的ubuntu远程机器上，我们在自己本地机器上配置了HINT所需的环境，但是远程机器上并没有，所以我们需要在CI中配置HINT。

故，我们来到.github/workflows/deploy.yml:

现在的内容是：

# Sample workflow for building and deploying a mdBook site to GitHub Pages
#
# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
#
name: Deploy mdBook site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      MDBOOK_VERSION: 0.4.36
    steps:
      - uses: actions/checkout@v4
      - name: Install mdBook
        run: |
          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
          rustup update
          cargo install --version ${MDBOOK_VERSION} mdbook
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: Build with mdBook
        run: mdbook build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./book

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

仔细回想，我们在本地配置HINT环境时，提到需要安装插件mdbook-admonish，于是我们照猫画虎地改写上述deploy.yml:

# Sample workflow for building and deploying a mdBook site to GitHub Pages
#
# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
#
name: Deploy mdBook site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      MDBOOK_VERSION: 0.4.36
      MDBOOK_ADMONISH_VERSION: "1.18.0" # Specify the version of mdbook-admonish
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust and mdBook
        run: |
          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
          rustup update
          cargo install --version ${MDBOOK_VERSION} mdbook
      - name: Install mdbook-admonish
        run: |
          cargo install mdbook-admonish --version ${MDBOOK_ADMONISH_VERSION}
          mdbook-admonish install ./ # This installs the required assets for admonish
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: Build with mdBook
        run: mdbook build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./book

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

注意对比，我们实际上就是在Build过程中新加了一步Install mdbook-admonish:

- name: Install mdbook-admonish
    run: |
        cargo install mdbook-admonish --version ${MDBOOK_ADMONISH_VERSION}
        mdbook-admonish install ./ # This installs the required assets for admonish

如此，我们的mdbook网页在本地和远端CI都已经部署完毕

一键部署

如果上述看的你头晕眼花，恭喜你，现在来到了经典的“白嫖环节” 🎆

Clone, customize, and push are all you need :))

这里我们提供了一键部署的template：

1. 本地环境还是要按照上述说的来配
2. 直接来到笔者的仓库，use this template
3. Clone repo! 本文提及的所有特性都已安排进去了，开箱即用！
4. 在本地做你自己的客制化修改
5. git add / commit / push三部曲

完结撒花 🚀