README - mdBook in Cargo.toml

[DJStompZone]

👀 I have searched open and closed issues and pull requests for duplicates, using these search terms:

• "mdbook"
• "mdbook this file"
• "mdbook cargo.toml"

✅ I have checked the latest main branch to see if this has already been fixed, in this file:

• README.md (line 27)

🌐URL to the section(s) of the book with this problem:

README.md, line 27

💬 Description of the problem:

The readme says "Building the book requires mdBook, ideally the same version that
rust-lang/rust uses in this file". However, mdBook being in its own category rather than under the generic "dependencies" section makes it easy to miss, creating the potential for confusion. (Frankly, when I started typing this issue, I myself was convinced it was missing, and only noticed it after doing a ctrl+f search to double check)

🔨 Suggested fix:

Dynamically insert the correct version for mdBook in the readme in order to make the documentation more clear, concise, and welcoming. This can be done with minimal difficulty via GitHub Actions:

1. Update README.md ✏

- Building the book requires [mdBook], ideally the same version that
+ Building the book requires [mdBook], ideally version ${mdBook_version}
- rust-lang/rust uses in [this file][rust-mdbook]. To get it:
+ To get it:
- $ cargo install mdbook --version <version_num>
+ $ cargo install mdbook --version ${mdBook_version}

2. Create workflow 🎬

name: Update mdBook Version in README

on:
  push:
    paths:
      - '**/Cargo.toml'

jobs:
  update-readme:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
      
      - name: Update README.md with actual mdBook version
        run: |
          NEW_VERSION=$(grep -oP 'version = "\K(.*)(?=")' Cargo.toml | tail -1)
          OLD_VERSION=$(grep -oP '\$ cargo install mdbook --version \K([0-9.]+)' README.md)
          if [ ! -z "$OLD_VERSION" ] && [ "$NEW_VERSION" != "$OLD_VERSION" ]; then

            # Update README.md, line 26
            sed -i "s|Building the book requires \[mdBook\], ideally version $OLD_VERSION|Building the book requires [mdBook], ideally version $NEW_VERSION|g" README.md

            # Update README.md, line 33
            sed -i "s|\$ cargo install mdbook --version $OLD_VERSION|\$ cargo install mdbook --version $NEW_VERSION|g" README.md

            git config --global user.name 'github-actions'
            git config --global user.email 'github-actions@github.com'
            git add README.md
            git commit -m "Update mdBook version to $NEW_VERSION in README" -m "This automatic commit updates the mdBook version directly in the README.md to match the version specified in Cargo.toml." || echo "No changes to commit"
            git push
          else
            echo "mdBook version is already up-to-date or not found in README.md."
          fi

---

Cheers!

--DJ

[chriskrycho]

Thanks for the suggestion! We'll need to decide whether we want to add that automation (automation is awesome but also has to be maintained over time!), but having a handy example is fantastic!