Skip to main content

Recent posts

mdBook 搭建记录

mdBook is a utility to create modern online books from Markdown files.

本文记录使用 mdBook 搭建在线文档的过程。

1. 安装 mdBook#

https://github.com/rust-lang/mdBook#Installation

brew install mdbook

2. 初始化#

在根目录下跑初始化命令，然后按着操作

mdbook init
# 下边的内容是命令行提示与输入的值
Do you want a .gitignore to be created? (y/n)
> y
What title would you like to give the book?
> blog

此命令运行运行结束后，在文件夹中会多出:

  • src 文件夹
  • .gitignore 文件
  • book.toml 配置文件
  • book 文件夹(编译后生成)

3. mdBook 基础配置#

不想打乱原本的文件结构，就删除了 src 文件夹。

由于 mdBook 通过 SUMMARY.md 文件读取文档结构，但之前已经通过 README.md 编写过。于是通过生成链接的方式解决: ln -s README.md SUMMARY.md，避免重复工作。

此外，还额外链接 ln -s README.md index.md，之后在 SUMMARY.md 中添加条目，才可以生成 index.html。

修改 book.toml 配置文件中的 src 和 title。

src = "./" # 修改为从根目录读取博客内容
title = "" # 由于在线文档中的标题不太美观。个人将其移除

4. 查看、生成在线文档#

该命令运行后可以在 http://localhost:3000 中查看在线文档。

mdbook serve

该命令运行后会生成静态网页在 book 文件夹中。可以用来上传服务器。

mdbook build

5. 集成 GitHub Actions & GitHub Pages#

主要依赖 actions-mdbook 实现。

首先在根目录下新建 .github/workflows/mdBook.yml 文件，之后将以下内容复制到文件中:

name: mdBook
on:
push:
branches:
- master
jobs:
deploy:
runs-on: macos-latest
steps:
- uses: actions/checkout@v2
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: 'latest'
- run: mdbook build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./book

然后在项目的设置中设置好对应的分支，等到 Action 运行成功就可以在链接中看到在线文档。

GitHub Pages