Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/peaceiris/actions-mdbook

GitHub Actions for mdBook (rust-lang/mdBook) ⚡️ Setup mdBook quickly and build your site fast. Linux (Ubuntu), macOS, and Windows are supported.
https://github.com/peaceiris/actions-mdbook

actions github-actions mdbook rust

Last synced: 5 days ago
JSON representation

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

Host: GitHub
URL: https://github.com/peaceiris/actions-mdbook
Owner: peaceiris
License: mit
Created: 2019-11-27T12:12:53.000Z (almost 5 years ago)
Default Branch: main
Last Pushed: 2024-04-08T15:50:17.000Z (7 months ago)
Last Synced: 2024-05-16T08:42:31.522Z (6 months ago)
Topics: actions, github-actions, mdbook, rust
Language: TypeScript
Homepage: https://github.com/marketplace/actions/mdbook-action
Size: 1.81 MB
Stars: 280
Watchers: 2
Forks: 20
Open Issues: 20
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

awesome-actions - GitHub Actions for mdBook
fucking-awesome-actions - GitHub Actions for mdBook
awesome-rust - peaceiris/actions-mdbook
awesome-rust-cn - peaceiris/actions-mdbook - mdBook的GitHub动作 (开发工具 Development tools / 构建系统 Build system)
awesome-workflows - GitHub Actions for mdBook
awesome-rust - peaceiris/actions-mdbook - GitHub Actions for mdBook (Development tools / Build system)
fucking-awesome-rust - peaceiris/actions-mdbook - GitHub Actions for mdBook (Development tools / Build system)
fucking-awesome-rust - peaceiris/actions-mdbook - GitHub Actions for mdBook (Development tools / Build system)

README

        


GitHub Actions for mdBook





  



[![license](https://img.shields.io/github/license/peaceiris/actions-mdbook.svg)](https://github.com/peaceiris/actions-mdbook/blob/main/LICENSE)

[![release](https://img.shields.io/github/release/peaceiris/actions-mdbook.svg)](https://github.com/peaceiris/actions-mdbook/releases/latest)

[![GitHub release date](https://img.shields.io/github/release-date/peaceiris/actions-mdbook.svg)](https://github.com/peaceiris/actions-mdbook/releases)

![Test](https://github.com/peaceiris/actions-mdbook/workflows/Test/badge.svg?branch=main&event=push)

[![CodeFactor](https://www.codefactor.io/repository/github/peaceiris/actions-mdbook/badge)](https://www.codefactor.io/repository/github/peaceiris/actions-mdbook)

[![codecov](https://codecov.io/gh/peaceiris/actions-mdbook/branch/main/graph/badge.svg)](https://codecov.io/gh/peaceiris/actions-mdbook)

[![Release Feed](https://img.shields.io/badge/release-feed-yellow)](https://github.com/peaceiris/actions-mdbook/releases.atom)

[rust-lang/mdBook] Setup Action.

[rust-lang/mdBook]: https://github.com/rust-lang/mdBook

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](#getting-started)

  - [⭐️ Create your workflow](#%EF%B8%8F-create-your-workflow)

- [Options](#options)

  - [⭐️ Use the latest version of mdBook](#%EF%B8%8F-use-the-latest-version-of-mdbook)

- [Tips](#tips)

  - [⭐️ Read mdBook version from file](#%EF%B8%8F-read-mdbook-version-from-file)

- [CHANGELOG](#changelog)

- [License](#license)

- [About Maintainer](#about-maintainer)

- [Maintainer Notes](#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](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-first-deployment-with-github_token)

[GitHub Actions for GitHub Pages]: https://github.com/peaceiris/actions-gh-pages

[![peaceiris/actions-gh-pages - GitHub](https://gh-card.dev/repos/peaceiris/actions-gh-pages.svg?fullname)](https://github.com/peaceiris/actions-gh-pages)

```yaml

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.

```yaml

- name: Setup mdBook

  uses: peaceiris/actions-mdbook@v2

  with:

    mdbook-version: 'latest'

```

This action fetches the latest version of mdBook by [mdbook — Homebrew Formulae](https://formulae.brew.sh/formula/mdbook)



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.

```sh

MDBOOK_VERSION=0.4.10

```

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

```yaml

    - 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.

```yaml

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.](https://github.com/peaceiris/docker-mdbook)



Back to TOC ☝️



## CHANGELOG

- [CHANGELOG.md](CHANGELOG.md)

## License

- [MIT License - peaceiris/actions-mdbook]

[MIT License - peaceiris/actions-mdbook]: https://github.com/peaceiris/actions-mdbook/blob/main/LICENSE

## About Maintainer

- [peaceiris homepage](https://peaceiris.com/)

- [GitHub Action Hero: Shohei Ueda - The GitHub Blog](https://github.blog/2020-03-22-github-action-hero-shohei-ueda/)

## Maintainer Notes

Run `npm` and `git commit` commands on a container.

**On Host**

```sh

# Docker

make build

make run

make run cmd="env"

make test

make commit msg="chore: Add Makefile"

# Release

./release.sh

```



Back to TOC ☝️