proposal: Add option to install mdbook-mermaid

[jorgecarleitao]

Checklist

• I am using the latest version of this action.
• I have read the latest README and followed the instructions.
• I have read the latest GitHub Actions official documentation and learned the basic spec and concepts.

Describe your proposal

Have an option / boolean parameter to install https://github.com/badboy/mdbook-mermaid, which allows to compile mermaid diagrams in guides docs.

Describe the solution you'd like

A simple parameter to optionally install mdbook-mermaid

Describe alternatives you've considered

Doing it manually

Additional context

None

[bgianfo]

I think generic preprocessor support would be awesome, there are a few I am interested in personally:

• mdbook-admonish
• mdbook-mermaid
• mdbook-toc
• mdbook-linkcheck

[peaceiris]

Other preprocessors except mdbook-admonish have pre-built binaries, so it looks possible to implement them.

Preprocessor name	Binary assets
mdbook-admonish	No
mdbook-mermaid	Yes
mdbook-toc	Yes
mdbook-linkcheck	Yes

[bgianfo]

Just as an FYI, mdbook-admonish now produces pre-built binaries.

[yaleman]

I'd like to see mdbook-template as well 😄

https://github.com/sgoudham/mdbook-template/releases/tag/v1.0.0

[zanglg]

I found mdbook-kroki-preprocessor, another excellent preprocessor which provides a unified API with support for many well-known textual graphs. Hope also give a support of.

[peaceiris]

👀

[expikr]

and mdbook-katex

SichangHe/mdbook_katex_static_css#8 (comment)

I propose editing the title of this issue to be about Preprocessors in general.

[kevinmichaelchen]

I'd like to add the mdbook-d2 plugin for consideration.

https://d2lang.com/

[bartvanderwal]

I found this issue wanting support for mdbook-quiz 🙏.

[dinosaure]

I actually use mdbook-graphviz, do you know a way to install it via the GitHub workflow.yml?

[SeniorMars]

This is the workflow I use. I don't like it but it works:

name: GitHub Pages
on:
  push:
    branches:
      - main
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

permissions:
  contents: write  # To push a branch
  pages: write  # To push to a GitHub Pages site
  id-token: write # To update the deployment status

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Install Rust & its package manager Cargo
      - name: Install cargo
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          profile: minimal
      # Cache installation assets
      - name: Cache cargo registry
        uses: actions/cache@v1
        with:
          path: ~/.cargo/registry
          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
      - name: Cache cargo index
        uses: actions/cache@v1
        with:
          path: ~/.cargo/git
          key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
      - name: Cache cargo build
        uses: actions/cache@v1
        with:
          path: target
          key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
      - name: Install mdbook and admonis plugin
        uses: actions-rs/cargo@v1
        with:
          command: install
          args: mdbook mdbook-admonish
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Build Book
        run: |
          mdbook-admonish install ./
          mdbook build
          touch ./book/.nojekyll
          touch ./book/CNAME
          echo 'lazy.rice.edu' >> book/CNAME
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: 'book'
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4```

[peaceiris]

I also maintain the docker image for mdBook including the following preprocessor. It seems to be useful for some of you who are using those preprocessors.

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

• mdbook-mermaid
• mdbook-toc
• mdbook-admonish

[SeniorMars]

This is useful, but it would be nice to have it within actions if possible.

[nicholasphair]

If the preprocessor publishes a binary you can add it somewhere on your path and be on your way.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v2
        with:
          mdbook-version: latest
      - run: |
          # Add mdbook-toc and mdbook-mermaid preprocessors.
          wget -qO- https://github.com/badboy/mdbook-toc/releases/download/0.14.2/mdbook-toc-0.14.2-x86_64-unknown-linux-gnu.tar.gz | tar xz -C /usr/local/bin
          wget -qO- https://github.com/badboy/mdbook-mermaid/releases/download/v0.14.1/mdbook-mermaid-v0.14.1-x86_64-unknown-linux-gnu.tar.gz | tar xz -C /usr/local/bin
          mdbook build

If it doesn't perhaps contribute to the project with a workflow to automatically publish the binaries. mdbook-toc provides a great example of how to do it. Of course being mindful of licenses and giving appropriate credit.