GitHub Actions for mdBook

rust-lang/mdBook Setup Action.

We can run mdBook on a virtual machine of GitHub Actions by this mdBook action. Linux, macOS, and Windows are supported.

OS (runs-on)	ubuntu-20.04, ubuntu-22.04	macos-latest	windows-2019
Support	✅️	✅️	✅️

Table of Contents

• Getting Started
  • ⭐️ Create your workflow
• Options
  • ⭐️ Use the latest version of mdBook
• Tips
  • ⭐️ Read mdBook version from file
• CHANGELOG
• License
• About Maintainer
• Maintainer Notes

Getting Started

⭐️ Create your workflow

An example workflow .github/workflows/gh-pages.yml with GitHub Actions for GitHub Pages. For the first deployment, we have to do this operation: First Deployment with GITHUB_TOKEN - peaceiris/actions-gh-pages

name: github pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v2
        with:
          mdbook-version: '0.4.10'
          # mdbook-version: 'latest'

      - run: mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

Back to TOC ☝️

Options

⭐️ Use the latest version of mdBook

Set mdbook-version: 'latest' to use the latest version of mdBook.

- name: Setup mdBook
  uses: peaceiris/actions-mdbook@v2
  with:
    mdbook-version: 'latest'

This action fetches the latest version of mdBook by mdbook — Homebrew Formulae

Back to TOC ☝️

Tips

⭐️ Read mdBook version from file

How to sync a mdBook version between a Docker Compose and a GitHub Actions workflow via .env file.

Write a MDBOOK_VERSION to the .env file like the following and push it to a remote branch.

MDBOOK_VERSION=0.4.10

Next, add a step to read a mdBook version from the .env file.

    - name: Read .env
      id: mdbook-version
      run: |
        . ./.env
        echo "::set-output name=MDBOOK_VERSION::${MDBOOK_VERSION}"

    - name: Setup mdBook
      uses: peaceiris/actions-mdbook@v2
      with:
        mdbook-version: '${{ steps.mdbook-version.outputs.MDBOOK_VERSION }}'

Here is a docker-compose.yml example.

version: '3'

services:
  mdbook:
    container_name: mdbook
    image: "peaceiris/mdbook:v${MDBOOK_VERSION}"
    # image: "peaceiris/mdbook:v${MDBOOK_VERSION}-rust"  # Large image including Rust compiler
    stdin_open: true
    tty: true
    ports:
      - 3000:3000
      - 3001:3001
    volumes:
      - ${PWD}:/book
    command:
      - serve
      - --hostname
      - '0.0.0.0'

The alpine base mdBook Docker image is provided on the following repository.

peaceiris/docker-mdbook: mdBook Alpine Base Docker Image.

Back to TOC ☝️

CHANGELOG

• CHANGELOG.md

License

• MIT License - peaceiris/actions-mdbook

About Maintainer

• peaceiris homepage
• GitHub Action Hero: Shohei Ueda - The GitHub Blog

Maintainer Notes

Run npm and git commit commands on a container.

On Host

# Docker
make build
make run
make run cmd="env"
make test
make commit msg="chore: Add Makefile"

# Release
./release.sh

Back to TOC ☝️