说明

使用 mdbook 构建文档，并集成 giscus 评论系统。

mdbook

安装

cargo install mdbook

创建项目

mdbook init my-first-book --theme
cd my-first-book

启动服务

mdbook serve --open

giscus

配置

参考说明：https://giscus.app/zh-CN

获取到 js 代码，格式如下：

<script src="https://giscus.app/client.js"
        data-repo="[在此输入仓库]"
        data-repo-id="[在此输入仓库 ID]"
        data-category="[在此输入分类名]"
        data-category-id="[在此输入分类 ID]"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

使用

vim theme/index.hbs

在 {{{ content }}} 下方添加获取到的代码，最终内容如下：

                <div id="content" class="content">
                    <main>
                        {{{ content }}}
                        <script src="https://giscus.app/client.js"
                                data-repo="poneding/my-first-book"
                                data-repo-id="R_kgDOMHy7cQ"
                                data-category="General"
                                data-category-id="DIC_kwDOMHy7cc4CgAPA"
                                data-mapping="pathname"
                                data-strict="0"
                                data-reactions-enabled="1"
                                data-emit-metadata="0"
                                data-input-position="top"
                                data-theme="preferred_color_scheme"
                                data-lang="zh-CN"
                                data-loading="lazy"
                                crossorigin="anonymous"
                                async>
                        </script>
                    </main>

配置 book.toml

vim "./book.toml"

编辑 book.toml 文件，添加或修改配置：

[book]
authors = ["poneding"]
language = "en"
multilingual = false
src = "src"
title = "My First Book"

[output.html]
default-theme = "light"
preferred-dark-theme = "navy"
git-repository-url = "https://github.com/poneding/my-first-book"
git-repository-icon = "fa-github"
edit-url-template = "https://github.com/poneding/my-first-book/edit/master/{path}"

GitHub Page 部署

创建 .github/workflows/deploy.yml 文件，写入如下内容：

name: Deploy
on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # To push a branch 
      pull-requests: write  # To create a PR from that branch
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: Install latest mdbook
      run: |
        tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
        url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
        mkdir mdbook
        curl -sSL $url | tar -xz --directory=./mdbook
        echo `pwd`/mdbook >> $GITHUB_PATH
    - name: Deploy GitHub Pages
      run: |
        # This assumes your book is in the root of your repository.
        # Just add a `cd` here if you need to change to another directory.
        mdbook build
        git worktree add gh-pages
        git config user.name "Deploy from CI"
        git config user.email ""
        cd gh-pages
        # Delete the ref to avoid keeping history.
        git update-ref -d refs/heads/gh-pages
        rm -rf *
        mv ../book/* .
        git add .
        git commit -m "Deploy $GITHUB_SHA to gh-pages"
        git push --force --set-upstream origin gh-pages