/actions-mdbook

GitHub Actions for mdBook (rust-lang/mdBook) ⚡️ Setup mdBook quickly and build your site fast. Linux (Ubuntu), macOS, and Windows are supported.

Primary LanguageTypeScriptMIT LicenseMIT

GitHub Actions for mdBook

GitHub Actions for mdBook thumbnail

license release GitHub release date Test CodeFactor codecov Release Feed

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-18.04, ubuntu-20.04 macos-latest windows-2019
Support ✅️ ✅️ ✅️

Table of Contents

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

peaceiris/actions-gh-pages - GitHub

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@v1
        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@v1
  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@v1
      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

License

About Maintainer

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 ☝️