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.

About Me

I'm peaceiris, interested in Static Site Generators and GitHub Actions.

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

Projects

• peaceiris/actions-gh-pages
• peaceiris/actions-hugo
• peaceiris/actions-mdbook
• peaceiris/actions-label-commenter
• peaceiris/emoji-ime-dictionary

Also, I spend my time on various repositories and forums to support communities.

actions-mdbook's Issues

proposal: Build the book somewhere other than root directory

Thank you for putting together this action!

Is your feature request related to a problem? Please describe.
I am having a bit of difficulty when building somewhere other than the root of the project. The book will build, but I am getting a 404 error when I go to the pages site.

Describe the solution you'd like
I am experimenting with using mdbook for the documentation of my Python projects. With that, I would like to keep with Python conventions to have my docs stored in project_root/docs. I set my actions yml file to use the following:

# ...
      - run: cd docs && mdbook build && cd ..

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/book

Here is a link to my gh-pages.yml.

Describe alternatives you've considered
I could keep everything in the project root, but it may be confusing for users to find the markdown files for the docs.

Additional context
I might be missing a final step in the process. My GitHub settings page shows that the book is being hosted at pages site. Not sure why I am getting a 404 error.

proposal: Support customized or forked version of mdBook

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

Hi, it's a great GitHub action to deploy my mdBook to my blog. However, I want to use this action to deploy my forked version mdBook. I have added some feature in it and would like to use them in this action.

I know that the mdBook executable is pull from the brew installer. If this action want to support this kind of feature, the executable MUST be built from source. I propose this action may provide input named mdbook-repository and mdbook-ref and provide the github URL and git SHA to it., respectively. The action would pull the code from it and build it from source to the executable. The latter stage would remain the same.

PS: I would like to try this issue

Describe the solution you'd like

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-repository: https://github.com/titaneric/mdBook.git
          mdbook-ref: master

      - 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

Describe alternatives you've considered

I may clone this repo, revise it and use my forked action instead.

Additional context

None

proposal: Add option to install `mdbook-mermaid`

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

proposal: Allow use with additional backends

Is your feature request related to a problem? Please describe.
I link to use mdbook-linkcheck to check links in my text. I haven't been able to get it working with this action.

Describe the solution you'd like
I'd like a feature where I can specify what additional backends I'm using and have them installed.

Describe alternatives you've considered
One alternative is to not use this action, and instead do something more manual as described in the mdbook-linkcheck readme

Additional context
My repo is https://github.com/substrate-developer-hub/recipes/

gha: Update stable tag v1 automatically with GitHub Actions

Is your feature request related to a problem? Please describe.
About stable tag v1.

Describe the solution you'd like
When a new version is released, the stable tag v1 should be updated automatically.

Describe alternatives you've considered
I can update the tag from my local repository. In case I may forget, so it is better to do it as a GitHub Actions workflow.

Additional context

git tag -d TAG_NAME
git push origin :refs/tags/TAG_NAME
git tag TAG_NAME
git push --tags origin

none.

Bug: Couldn't open SUMMARY.md

Describe the bug
Explicitly setting mdbook build path and instead resulting in the following error:

[ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md
[ERROR] (mdbook::utils): 	Caused By: No such file or directory (os error 2)

To Reproduce
Simply running the GitHub workflow

Expected behavior
mdbook build to run and complete.

Screenshots
If applicable, add screenshots to help explain your problem.

Your YAML file
nurodev/atlas/blob/master/.github/workflows/book.yml

Additional context
I have also done a sanity check and logged the current working directory when the step is run and it clearly shows that the book contents is present and ready to be build:

/home/runner/work/atlas/atlas/book
book.toml
custom.css
now.json
src
2020-01-08 16:54:46 [ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md
2020-01-08 16:54:46 [ERROR] (mdbook::utils): 	Caused By: No such file or directory (os error 2)
##[error]Process completed with exit code 101.

chore: Update Dockerfile

chore: update git by peaceiris · Pull Request #150 · peaceiris/actions-hugo

update lint-staged

chore: Add engines field

peaceiris/actions-hugo@aeba654

fix: Rename RUNNER_TEMPDIRECTORY to RUNNER_TEMP

deps: Add ESLint Plugin for TypeScript

cf. peaceiris/actions-hugo#131

• ESLint Plugin TypeScript
• eslint-plugin-jest - npm

TODO

• Sync npm tasks.
• Comment out cache steps

bug: """libc.so.6: version `GLIBC_2.29' not found""" on Ubuntu 18.04 with latest mdbook (0.4.21)

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 the bug

Is Ubuntu 18.04 still supported?

Relevant links

Public repository: https://github.com/Dhghomon/easy_rust/
YAML workflow: https://github.com/Dhghomon/easy_rust/blob/0e3e975bff562124bb4c8b1a5961a75fae01715b/.github/workflows/github-pages.yml

Relevant log output

Run peaceiris/actions-mdbook@v1
mdbook version: 0.4.21
Operating System: unknown-linux-gnu
toolURL: https://github.com/rust-lang/mdBook/releases/download/v0.4.21/mdbook-v0.4.21-x86_64-unknown-linux-gnu.tar.gz
/bin/tar xz --warning=no-unknown-keyword -C /home/runner/tmp -f /home/runner/work/_temp/bc8b8fa7-2411-4a7b-b503-cecaabd29ffd
/home/runner/toolbin/mdbook --version
/home/runner/toolbin/mdbook: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.29' not found (required by /home/runner/toolbin/mdbook)
/home/runner/toolbin/mdbook: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found (required by /home/runner/toolbin/mdbook)

Run mdbook build
mdbook: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.29' not found (required by mdbook)
mdbook: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found (required by mdbook)
Error: Process completed with exit code 1.

Additional context.

Action Run

proposal: Allow SemVer compatible updates

Is your feature request related to a problem? Please describe.

Unless i'm missing something the current version only allows getting a specific release version or the latest.
I would like to be able to get the latest SemVer compatible version.
So if i were using the 0.3 version of mdbook it would automatically get 0.3.1, 0.3.2, 0.3.3 etc. as they were released.

Describe the solution you'd like

Allow a syntax like '^0.3' to get the latest minor version.
A separate SemVer option that could be set to true could also be fine

Describe alternatives you've considered

Updating the version manually so when 0.4.2 gets released i would have to update my CI.
I could also try fetching the latest minor version outside of this action and then supply that

Additional context
Examples from the actions-rs/cargo action

      - name: install mdbook
        uses: actions-rs/cargo@v1
        with:
          command: install
          args: --vers "^0.3" mdbook

proposal: Automate Release process

Is your feature request related to a problem? Please describe.
When I create a new release or prerelease, release notes will be created automatically.

Describe the solution you'd like
Use the following tools.

• conventional-changelog/conventional-changelog: Generate changelogs and release notes from a project's commit messages and metadata.

Describe alternatives you've considered
none.

Additional context

• Test on playground-actions/release.yml
• commitizen/cz-cli: The commitizen command line utility.

proposal: Add and enable mdbook-link check by default

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

Thank you for the helpful project!

Checking for broken links is such a common and necessary activity that adding default support for it would be super.

https://github.com/Michael-F-Bryan/mdbook-linkcheck#getting-started has a short script for getting a link checker.

Describe the solution you'd like

I think that all that would be needed would be for users to specify a step in their toml file:

[output.linkcheck]

At least on my machine, when I set up the link checker with the below script, everything runs as expected:

RELEASE=https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/v0.7.7/mdbook-linkcheck.x86_64-apple-darwin.zip
mkdir -p mdbook-linkcheck && cd "$_" && \
  curl -L $RELEASE -o mdbook-linkcheck.zip && \
  unzip "$_" && \
  chmod +x mdbook-linkcheck && \
  export PATH=$PWD:$PATH && \
  cd ..

Describe alternatives you've considered

Perhaps a short link in the README to the link checker.

Additional context

Thank you very much!

proposal: Add Tips (Read mdBook version from file)

Is your feature request related to a problem? Please describe.
cf. Read Hugo version from file - peaceiris/actions-hugo

Describe the solution you'd like
Add an example workflow and docker-compose.yml

Describe alternatives you've considered
none.

Additional context
none.

refactor: Add readonly

feat: Add option fetch-from

Is your feature request related to a problem? Please describe.

An option that fetching the latest version from value.

with:
  fetch-from: 'github'  # default: 'brew'

Describe the solution you'd like
Provide this option.

Describe alternatives you've considered
N/A

Additional context
A workaround for GitHub API limitation.

- name: Get the latest version
  id: mdbook_version
  run: |
    MDBOOK_VERSION="$(curl -fsi "https://github.com/${GITHUB_REPOSITORY}/releases/latest" | awk -F/ '/^Location:/ {print $(NF)}')"
    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 }}'

fix: action failure status

fix: action failure status by peaceiris · Pull Request #9 · peaceiris/actions-pixela

fix: api.github tag_name

• Add replace('v', '')
• Add test

gha: Check whether did ncc or not

Is your feature request related to a problem? Please describe.
About lib/index.js

Describe the solution you'd like
Add a check step to the test workflow whether did ncc or not.

Describe alternatives you've considered
none.

Additional context
none.

proposal: update to Node.js 20

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

Currently the following warning will be generated when using this action:

Node.js 16 actions are deprecated. Please update the following actions to use Node.js 20: peaceiris/actions-mdbook@v1. For more information see: https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/.

Describe the solution you'd like

Update to Node.js 20.

Describe alternatives you've considered

Use something else.

Additional context

Biannual occurrence: #465

proposal: Run under node16

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

Many thanks for maintaining this action.

Github Actions has deprecated node12 runners in favour of node 16 (ETA: Summer 2023): see https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/

Users of this action are now seeing a warning:

Node.js 12 actions are deprecated. For more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/. Please update the following actions to use Node.js 16: peaceiris/actions-mdbook, peaceiris/actions-gh-pages

Would it be possible to bump node from 12 to 16?

Describe the solution you'd like

Similar to peaceiris/actions-gh-pages#677

Describe alternatives you've considered

N/A

Additional context

N/A

"cannot execute binary file" error

I'm getting the following error when when trying to run an actions-mdbook installed mdbook binary:

/Users/runner/work/_temp/bfe5655f-fa0a-410b-9608-62a44511a89b.sh: line 2: /Users/runner/toolbin/mdbook: cannot execute binary file

Here's a link to the GitHub actions run.

It looks like the last previous successful run was two days ago. Might something have changed between now and then that's causing this error?

Bug: mdbook cannot be published and resulted 404 at GitHub Pages

Describe the bug
I was following the guides at the docs, including doing a dummy first release, but has no effect.

Settings of my repo GitHub pages:

My action config yaml:

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

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

      - run: mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

To Reproduce
Follow the docs

Expected behavior
mdbook can be pushed from the book directory and rendered at GitHub pages

Screenshots
Please see above

Your YAML file
book repo: https://github.com/iandyh/shibuya-book

Additional context
Add any other context about the problem here.