Centralize tool versions and improve build consistency

.github/workflows/deploy.yml

@@ -1,4 +1,6 @@
 name: Deploy mdBook to GitHub Pages
+# Tool versions are managed in versions.toml at the repository root.
+# To update mdbook or plugin versions, edit versions.toml and the CI will automatically use them.
 
 on:
   # Runs on pushes targeting the default branch
@@ -26,22 +28,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
-      - name: Install mdBook
-        run: cargo install mdbook
+      - name: Install mdBook and plugins
+        run: |
+          chmod +x scripts/install-tools.sh
+          ./scripts/install-tools.sh
 
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
 
       - name: Build with mdBook
-        run: |
-          cd better-code
-          mdbook build
+        run: mdbook build ./better-code
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: ./better-code/book
 

.tool-versions

@@ -0,0 +1,7 @@
+# Tool versions for asdf version manager
+# See: https://asdf-vm.com/
+#
+# Note: For mdbook and plugin versions, see versions.toml
+# Use the install scripts in better-code/ to install the correct versions
+rust stable
+

README.md

@@ -8,90 +8,121 @@ We're migrating from using Jekyll to using
 [mdBook](https://github.com/rust-lang/mdBook). The mdBook version is located in
 the `./better-code` directory and includes automated CI/CD deployment to GitHub Pages.
 
-## Installing and updating mdBook
+The published book is available at: https://stlab.github.io/better-code/
 
-Install [Rust and
-Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html):
+## Prerequisites
 
-Linux and macOS:
+Install [Rust and Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html):
 
-```
+**Linux and macOS:**
+```bash
 curl https://sh.rustup.rs -sSf | sh
 ```
 
-On Windows, you can download the installer from
-[here](https://win.rustup.rs/).
+**Windows:**
+Download the installer from [here](https://win.rustup.rs/).
 
-Once you have Rust and Cargo installed, you can install or upgrade mdBook by running:
+## Installing mdBook and Plugins
 
-```
-cargo install mdbook
+**Important**: To ensure consistency between local development and CI, all tool
+versions are centrally managed in `versions.toml`. Use the provided installation
+scripts to automatically install the correct versions:
+
+**Linux/macOS:**
+```bash
+./scripts/install-tools.sh
 ```
 
-## Building the book
+**Windows (PowerShell):**
+```powershell
+.\scripts\install-tools.ps1
+```
 
-To build the book, run:
+These scripts automatically install mdBook and all required plugins using the
+versions specified in `versions.toml`. This is the same file used by CI, ensuring
+perfect consistency.
 
+**Manual Installation:**
+If you prefer to install manually, check `versions.toml` for the current version
+numbers, then run:
+```bash
+cargo install mdbook --version <version-from-toml>
+cargo install mdbook-katex --version <version-from-toml>
 ```
+
+## Building and Serving the Book
+
+To build and serve the book locally with live reload:
+
+```bash
 mdbook serve ./better-code
 ```
 
-Open the browser to http://localhost:3000 to see the book. You can use the
+This will start a local server at http://localhost:3000. You can use the
 Simple Browser in VSCode/Cursor to view the book while editing.
 
-## Automated Deployment
+To build the book without serving:
 
-The mdBook is automatically built and deployed to GitHub Pages using GitHub Actions.
-When you push changes to the main branch:
+```bash
+mdbook build ./better-code
+```
 
-1. GitHub Actions will build the book using mdBook
-2. The built book will be deployed to GitHub Pages
-3. The book will be available at https://stlab.github.io/better-code/
+The built book will be in the `./better-code/book/` directory.
 
-No manual deployment steps are required!
+## Adding and Editing Content
 
-### Conventions and Guidelines
+1. Edit existing chapters in `better-code/src/`
+2. Add new chapters by creating new `.md` files in `better-code/src/`
+3. Update `better-code/src/SUMMARY.md` to include new chapters in the table of contents
+4. The book will automatically rebuild and redeploy when you push changes to the main branch
+
+### Content Conventions
 
 * Avoid unnecessary HTML tags; use Markdown formatting to the degree possible.
 * Wrap lines at 80 columns to support diff-friendly change tracking.
-* Chapters are represented as individual Markdown files in the chapters/
-  subdirectory.
-* Each chapter begins with a 2nd-level heading, e.g. `## Chapter Name`.  All
+* Each chapter begins with a 2nd-level heading, e.g. `## Chapter Name`. All
   other headings in a chapter are 3rd-level and below.
-* Each file's name starts with a 4-digit number that determines its order in the
-  overall document.  Initial numbering is spaced by 100s.
 * Maintain stable file names and heading titles for linkability until another
   solution is in place.
 
-### Older draft
+## Automated Deployment
 
-Please see the [latest published draft](https://stlab.github.io/better-code/)
-for information about the motivation for this project.
+The mdBook is automatically built and deployed to GitHub Pages using GitHub Actions.
+When you push changes to the main branch:
 
-### Infrastructure
+1. GitHub Actions builds the book using mdBook with versions from `versions.toml`
+2. The built book is deployed to GitHub Pages
+3. The book becomes available at https://stlab.github.io/better-code/
 
-The book is being migrated from [Jekyll](https://jekyllrb.com) to [mdBook](https://github.com/rust-lang/mdBook).
-The new mdBook version is automatically built and deployed to [GitHub Pages](https://pages.github.com) using GitHub Actions.
+No manual deployment steps are required!
 
-The legacy Jekyll files remain in the root directory for reference during the transition.
+## Dependency Management
 
-### Running a local server
+All tool versions (mdBook, plugins, and future tools like Swift) are managed in
+`versions.toml` at the repository root. To update a version:
 
-If you are able to install the necessary parts for jekyll,
+1. Edit the version number in `versions.toml`
+2. Run the appropriate install script to update locally
+3. Test your changes
+4. Commit - CI will automatically use the new version
 
-```
+## Legacy Jekyll Content
+
+The legacy Jekyll files remain in the `archive/` directory for reference during
+the transition. You can ignore these unless you're working on the migration.
+
+**Running the Jekyll version (for reference only):**
+
+If you need to run the legacy Jekyll site:
+
+```bash
 bundle exec jekyll serve -l
 ```
 
-will start a server for the site at http://localhost:4000.
+This will start a server at http://localhost:4000.
 
-Creating a complete installation of jekyll and all the parts needed for github
-pages development can be fraught.  If you install
-[docker-compose](https://docs.docker.com/compose/), you can start the server
-by invoking
+Alternatively, if you have [docker-compose](https://docs.docker.com/compose/):
 
-```
+```bash
 docker-compose up
 ```
-
-in the root directory of your working copy.

better-code/book.toml

@@ -1,7 +1,6 @@
 [book]
 authors = ["Sean Parent"]
 language = "en"
-multilingual = false
 src = "src"
 title = "Better Code"
 description = "A principled and rigorous approach to software development"

scripts/install-tools.ps1

@@ -0,0 +1,76 @@
+# Install mdBook and plugins using versions from ../versions.toml
+# This ensures consistency between local development and CI
+
+$ErrorActionPreference = "Stop"
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$VersionsFile = Join-Path (Split-Path -Parent $ScriptDir) "versions.toml"
+
+# Function to parse TOML and extract version
+function Get-ToolVersion {
+    param (
+        [string]$Tool,
+        [string]$Section = ""
+    )
+
+    $content = Get-Content $VersionsFile -Raw
+
+    if ($Section) {
+        # Extract from section like [mdbook-plugins]
+        $pattern = "(?ms)\[$Section\].*?$Tool\s*=\s*`"([^`"]+)`""
+    } else {
+        # Extract from top-level section like [mdbook]
+        $pattern = "(?ms)\[$Tool\].*?version\s*=\s*`"([^`"]+)`""
+    }
+
+    if ($content -match $pattern) {
+        return $Matches[1]
+    }
+    return $null
+}
+
+# Function to get all plugins from [mdbook-plugins] section
+function Get-MdbookPlugins {
+    $content = Get-Content $VersionsFile -Raw
+    $plugins = @{}
+
+    if ($content -match '(?ms)\[mdbook-plugins\](.*?)(\[|$)') {
+        $section = $Matches[1]
+        $lines = $section -split "`n"
+
+        foreach ($line in $lines) {
+            if ($line -match '^([a-zA-Z0-9_-]+)\s*=\s*"([^"]+)"') {
+                $plugins[$Matches[1]] = $Matches[2]
+            }
+        }
+    }
+
+    return $plugins
+}
+
+Write-Host "Reading versions from $VersionsFile..." -ForegroundColor Cyan
+
+# Install mdBook
+$MdbookVersion = Get-ToolVersion -Tool "mdbook"
+if ($MdbookVersion) {
+    Write-Host "`nInstalling mdBook $MdbookVersion..." -ForegroundColor Cyan
+    cargo install mdbook --version $MdbookVersion
+} else {
+    Write-Host "Error: Could not find mdbook version in versions.toml" -ForegroundColor Red
+    exit 1
+}
+
+# Install mdBook plugins
+Write-Host "`nInstalling mdBook plugins..." -ForegroundColor Cyan
+
+$plugins = Get-MdbookPlugins
+foreach ($plugin in $plugins.GetEnumerator()) {
+    Write-Host "Installing $($plugin.Key) $($plugin.Value)..." -ForegroundColor Cyan
+    cargo install $plugin.Key --version $plugin.Value
+}
+
+Write-Host "`n✓ Installation complete!" -ForegroundColor Green
+Write-Host "`nInstalled versions:" -ForegroundColor Cyan
+mdbook --version
+cargo install --list | Select-String "mdbook"
+