mdBook GitHub Actions 使用教程
1、项目介绍
actions-mdbook
是一个 GitHub Actions 项目,用于在 GitHub Actions 环境中快速设置和构建 mdBook
站点。mdBook
是一个用 Rust 编写的工具,用于创建书籍和文档网站。actions-mdbook
支持 Linux (Ubuntu)、macOS 和 Windows 平台。
2、项目快速启动
创建工作流文件
在你的 GitHub 仓库中,创建一个 .github/workflows/mdbook.yml
文件,并添加以下内容:
name: mdBook CI
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: 'latest'
- name: Build
run: mdbook build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./book
解释
- Checkout: 检出仓库代码。
- Setup mdBook: 使用
peaceiris/actions-mdbook
设置mdBook
。 - Build: 构建
mdBook
站点。 - Deploy: 使用
peaceiris/actions-gh-pages
部署到 GitHub Pages。
3、应用案例和最佳实践
应用案例
- 文档网站: 使用
mdBook
创建项目文档网站,如 API 文档、用户手册等。 - 电子书: 使用
mdBook
创建电子书,如技术书籍、教程等。
最佳实践
- 版本控制: 使用 GitHub 进行版本控制,确保文档的每次更新都有记录。
- 自动化部署: 使用 GitHub Actions 自动化构建和部署流程,减少手动操作。
- 多平台支持: 确保文档在不同平台(Linux、macOS、Windows)上都能正常构建和查看。
4、典型生态项目
- mdBook: 核心项目,用于创建和管理书籍和文档网站。
- GitHub Actions: 用于自动化构建和部署流程。
- peaceiris/actions-gh-pages: 用于将构建好的站点部署到 GitHub Pages。
通过以上步骤和实践,你可以快速上手并使用 actions-mdbook
项目,创建和部署高质量的文档网站。