Starting migration to mdBook.

Author: sean-parent

.github/workflows/deploy.yml

@@ -0,0 +1,64 @@
+name: Deploy mdBook to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        
+      - name: Setup Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+          
+      - name: Install mdBook
+        run: cargo install mdbook
+        
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+        
+      - name: Build with mdBook
+        run: |
+          cd better-code
+          mdbook build
+          
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./better-code/book
+
+  # Deployment job
+  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@v2 

README.md

@@ -1,14 +1,54 @@
-## Welcome to Better Code
+# Welcome to Better Code
 
 This is the development home of the STLab Better Code course.
 
-Please see the [latest published draft](https://stlab.github.io/better-code/)
-for information about the motivation for this project.
+## Working with the Book
 
-### Infrastructure
+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
+
+Install [Rust and
+Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html):
+
+Linux and macOS:
+
+```
+curl https://sh.rustup.rs -sSf | sh
+```
+
+On Windows, you can download the installer from
+[here](https://win.rustup.rs/).
+
+Once you have Rust and Cargo installed, you can install or upgrade mdBook by running:
+
+```
+cargo install mdbook
+```
 
-The reference is developed as a [Jekyll](https://jekyllrb.com) website,
-currently being served by [GitHub Pages](https://pages.github.com).
+## Building the book
+
+To build the book, run:
+
+```
+mdbook serve ./better-code
+```
+
+Open the browser to http://localhost:3000 to see the book. You can use the
+Simple Browser in VSCode/Cursor to view the book while editing.
+
+## Automated Deployment
+
+The mdBook is automatically built and deployed to GitHub Pages using GitHub Actions.
+When you push changes to the main branch:
+
+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/
+
+No manual deployment steps are required!
 
 ### Conventions and Guidelines
 
@@ -23,6 +63,18 @@ currently being served by [GitHub Pages](https://pages.github.com).
 * Maintain stable file names and heading titles for linkability until another
   solution is in place.
 
+### Older draft
+
+Please see the [latest published draft](https://stlab.github.io/better-code/)
+for information about the motivation for this project.
+
+### Infrastructure
+
+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.
+
+The legacy Jekyll files remain in the root directory for reference during the transition.
+
 ### Running a local server
 
 If you are able to install the necessary parts for jekyll,

better-code/README.md

@@ -0,0 +1,52 @@
+# Better Code - mdBook
+
+This directory contains the mdBook version of the Better Code course.
+
+## Local Development
+
+### Prerequisites
+
+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
+```
+
+**Windows:**
+Download the installer from [here](https://win.rustup.rs/).
+
+### Install mdBook
+
+```bash
+cargo install mdbook
+```
+
+### Building and Serving the Book
+
+To build and serve the book locally:
+
+```bash
+mdbook serve
+```
+
+This will start a local server at `http://localhost:3000`.
+
+To just build the book without serving:
+
+```bash
+mdbook build
+```
+
+The built book will be in the `book/` directory.
+
+## Deployment
+
+The book is automatically built and deployed to GitHub Pages using GitHub Actions when changes are pushed to the main branch.
+
+## Adding Content
+
+1. Edit existing chapters in the `src/` directory
+2. Add new chapters by creating new `.md` files in `src/`
+3. Update `src/SUMMARY.md` to include new chapters in the table of contents
+4. The book will automatically rebuild when you push changes to GitHub 

better-code/book.toml

@@ -4,3 +4,19 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Better Code"
+description = "A principled and rigorous approach to software development"
+
+[build]
+build-dir = "book"
+
+[output.html]
+git-repository-url = "https://github.com/stlab/better-code"
+edit-url-template = "https://github.com/stlab/better-code/edit/main/better-code/src/{path}"
+site-url = "/better-code/"
+cname = "stlab.github.io"
+
+[output.html.search]
+enable = true
+
+[output.html.print]
+enable = true