Skip to content

Commit e0809a6

Browse files
sean-parentsean-parent
authored
Merge pull request #36 from stlab/sean-parent/dependency-management
Centralize tool versions and improve build consistency
2 parents ff45c64 + 39cfff9 commit e0809a6

10 files changed

Lines changed: 332 additions & 142 deletions

File tree

‎.github/workflows/build-pr.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: Validate PR Build
2+
3+
on:
4+
pull_request:
5+
branches: ["main"]
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
validate:
12+
uses: ./.github/workflows/build.yml
13+

‎.github/workflows/build.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Build mdBook
2+
3+
on:
4+
workflow_call:
5+
outputs:
6+
artifact-path:
7+
description: "Path to the built book artifact"
8+
value: ${{ jobs.build.outputs.artifact-path }}
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
build:
15+
strategy:
16+
matrix:
17+
os: [ubuntu-latest, windows-latest]
18+
runs-on: ${{ matrix.os }}
19+
outputs:
20+
artifact-path: ./better-code/book
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v6
24+
25+
# Cache Rust toolchain and cargo registry
26+
- name: Cache Rust
27+
uses: actions/cache@v4
28+
with:
29+
path: |
30+
~/.cargo/bin/
31+
~/.cargo/registry/index/
32+
~/.cargo/registry/cache/
33+
~/.cargo/git/db/
34+
~/.cargo/.crates.toml
35+
~/.cargo/.crates2.json
36+
key: ${{ runner.os }}-cargo-${{ hashFiles('versions.txt') }}
37+
restore-keys: |
38+
${{ runner.os }}-cargo-
39+
40+
- name: Install mdBook and plugins (Linux)
41+
if: runner.os != 'Windows'
42+
run: |
43+
chmod +x scripts/install-tools.sh
44+
./scripts/install-tools.sh
45+
46+
- name: Install mdBook and plugins (Windows)
47+
if: runner.os == 'Windows'
48+
run: .\scripts\install-tools.ps1
49+
50+
- name: Build with mdBook
51+
run: mdbook build ./better-code
52+
53+
- name: Upload build artifact
54+
uses: actions/upload-artifact@v4
55+
with:
56+
name: mdbook-build-${{ matrix.os }}
57+
path: ./better-code/book
58+
retention-days: 1
59+

‎.github/workflows/deploy.yml‎

Lines changed: 24 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,52 @@
1-
name: Deploy mdBook to GitHub Pages
1+
name: Deploy to GitHub Pages
2+
# Tool versions are managed in versions.txt at the repository root.
3+
# To update mdbook or plugin versions, edit versions.txt and the CI will automatically use them.
24

35
on:
4-
# Runs on pushes targeting the default branch
56
push:
67
branches: ["main"]
7-
8-
# Allows you to run this workflow manually from the Actions tab
98
workflow_dispatch:
109

11-
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
1210
permissions:
1311
contents: read
1412
pages: write
1513
id-token: write
1614

17-
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18-
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
1915
concurrency:
2016
group: "pages"
2117
cancel-in-progress: false
2218

2319
jobs:
24-
# Build job
2520
build:
26-
runs-on: ubuntu-latest
27-
steps:
28-
- name: Checkout
29-
uses: actions/checkout@v4
30-
31-
- name: Install mdBook
32-
run: cargo install mdbook
33-
34-
- name: Setup Pages
35-
id: pages
36-
uses: actions/configure-pages@v5
37-
38-
- name: Build with mdBook
39-
run: |
40-
cd better-code
41-
mdbook build
42-
43-
- name: Upload artifact
44-
uses: actions/upload-pages-artifact@v3
45-
with:
46-
path: ./better-code/book
21+
uses: ./.github/workflows/build.yml
22+
permissions:
23+
contents: read
4724

48-
# Deployment job
4925
deploy:
5026
environment:
5127
name: github-pages
5228
url: ${{ steps.deployment.outputs.page_url }}
5329
runs-on: ubuntu-latest
5430
needs: build
31+
permissions:
32+
pages: write
33+
id-token: write
5534
steps:
35+
- name: Download build artifact
36+
uses: actions/download-artifact@v4
37+
with:
38+
name: mdbook-build-ubuntu-latest
39+
path: ./book
40+
41+
- name: Setup Pages
42+
id: pages
43+
uses: actions/configure-pages@v5
44+
45+
- name: Upload Pages artifact
46+
uses: actions/upload-pages-artifact@v4
47+
with:
48+
path: ./book
49+
5650
- name: Deploy to GitHub Pages
5751
id: deployment
5852
uses: actions/deploy-pages@v4

‎.tool-versions‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Tool versions for asdf version manager
2+
# See: https://asdf-vm.com/
3+
#
4+
# Note: For mdbook and plugin versions, see versions.txt
5+
# Use the install scripts to install the correct versions: ./scripts/install-tools.sh
6+
rust stable
7+

‎README.md‎

Lines changed: 79 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,117 @@
1-
# Welcome to Better Code
1+
# Better Code
22

3-
This is the development home of the STLab Better Code course.
3+
Development repository for the STLab Better Code course.
44

5-
## Working with the Book
5+
**Read the book:** https://stlab.github.io/better-code/
66

7-
We're migrating from using Jekyll to using
8-
[mdBook](https://github.com/rust-lang/mdBook). The mdBook version is located in
9-
the `./better-code` directory and includes automated CI/CD deployment to GitHub Pages.
7+
## Quick Start
108

11-
## Installing and updating mdBook
9+
### 1. Install Prerequisites
1210

13-
Install [Rust and
14-
Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html):
11+
Install [Rust and Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html).
1512

16-
Linux and macOS:
1713

18-
```
19-
curl https://sh.rustup.rs -sSf | sh
20-
```
21-
22-
On Windows, you can download the installer from
23-
[here](https://win.rustup.rs/).
24-
25-
Once you have Rust and Cargo installed, you can install or upgrade mdBook by running:
14+
### 2. Install mdBook and Plugins
2615

16+
**Linux/macOS:**
17+
```bash
18+
./scripts/install-tools.sh
2719
```
28-
cargo install mdbook
20+
21+
**Windows (PowerShell):**
22+
```powershell
23+
.\scripts\install-tools.ps1
2924
```
3025

31-
## Building the book
26+
These scripts install mdBook and all required plugins using versions from `versions.txt`.
3227

33-
To build the book, run:
28+
### 3. Build and Serve
3429

35-
```
30+
```bash
3631
mdbook serve ./better-code
3732
```
3833

39-
Open the browser to http://localhost:3000 to see the book. You can use the
40-
Simple Browser in VSCode/Cursor to view the book while editing.
34+
Open http://localhost:3000 in your browser.
4135

42-
## Automated Deployment
36+
## Contributing
4337

44-
The mdBook is automatically built and deployed to GitHub Pages using GitHub Actions.
45-
When you push changes to the main branch:
38+
### Editing Content
4639

47-
1. GitHub Actions will build the book using mdBook
48-
2. The built book will be deployed to GitHub Pages
49-
3. The book will be available at https://stlab.github.io/better-code/
40+
1. Edit markdown files in `better-code/src/`
41+
2. Add new chapters by creating `.md` files and updating `better-code/src/SUMMARY.md`
42+
3. Changes automatically rebuild when you push to the main branch
5043

51-
No manual deployment steps are required!
44+
### Content Conventions
5245

53-
### Conventions and Guidelines
46+
* Use Markdown formatting; avoid unnecessary HTML
47+
* Wrap lines at 80 columns for diff-friendly change tracking
48+
* Start each chapter with a level-2 heading (`## Chapter Name`)
49+
* Use level-3+ headings within chapters
50+
* Keep file names and heading titles stable for linkability
5451

55-
* Avoid unnecessary HTML tags; use Markdown formatting to the degree possible.
56-
* Wrap lines at 80 columns to support diff-friendly change tracking.
57-
* Chapters are represented as individual Markdown files in the chapters/
58-
subdirectory.
59-
* Each chapter begins with a 2nd-level heading, e.g. `## Chapter Name`. All
60-
other headings in a chapter are 3rd-level and below.
61-
* Each file's name starts with a 4-digit number that determines its order in the
62-
overall document. Initial numbering is spaced by 100s.
63-
* Maintain stable file names and heading titles for linkability until another
64-
solution is in place.
52+
## Deployment
6553

66-
### Older draft
54+
### CI/CD Pipeline
6755

68-
Please see the [latest published draft](https://stlab.github.io/better-code/)
69-
for information about the motivation for this project.
56+
**Pull Requests:**
57+
- Validates build on Ubuntu and Windows
58+
- No deployment; PR check shows build status
7059

71-
### Infrastructure
60+
**Main Branch:**
61+
- Builds book using mdBook with versions from `versions.txt`
62+
- Deploys to GitHub Pages
63+
- Available at https://stlab.github.io/better-code/
7264

73-
The book is being migrated from [Jekyll](https://jekyllrb.com) to [mdBook](https://github.com/rust-lang/mdBook).
74-
The new mdBook version is automatically built and deployed to [GitHub Pages](https://pages.github.com) using GitHub Actions.
65+
### Managing Dependencies
7566

76-
The legacy Jekyll files remain in the root directory for reference during the transition.
67+
All tool versions are centrally managed in `versions.txt`. To update:
7768

78-
### Running a local server
69+
1. Edit version number in `versions.txt`
70+
2. Run the appropriate install script locally
71+
3. Test with `mdbook serve ./better-code`
72+
4. Commit - CI automatically uses the new version
7973

80-
If you are able to install the necessary parts for jekyll,
74+
## Project Structure
8175

8276
```
83-
bundle exec jekyll serve -l
77+
better-code/ # mdBook source and configuration
78+
├── src/ # Markdown chapter files
79+
├── book.toml # mdBook configuration
80+
└── book/ # Generated HTML (gitignored)
81+
82+
scripts/ # Installation scripts
83+
├── install-tools.sh # Linux/macOS
84+
└── install-tools.ps1 # Windows
85+
86+
versions.txt # Single source of truth for tool versions
87+
archive/ # Legacy Jekyll site (for reference only)
8488
```
8589

86-
will start a server for the site at http://localhost:4000.
90+
## Advanced Usage
8791

88-
Creating a complete installation of jekyll and all the parts needed for github
89-
pages development can be fraught. If you install
90-
[docker-compose](https://docs.docker.com/compose/), you can start the server
91-
by invoking
9292

93+
### Building Without Serving
94+
95+
```bash
96+
mdbook build ./better-code
9397
```
94-
docker-compose up
98+
99+
Output will be in `./better-code/book/`.
100+
101+
102+
## Legacy Content
103+
104+
The `archive/` directory contains the legacy Jekyll site for reference during migration.
105+
You can safely ignore it unless working on migration tasks.
106+
107+
To run the Jekyll version (not recommended for regular development):
108+
109+
```bash
110+
bundle exec jekyll serve -l # Starts server at http://localhost:4000
95111
```
96112

97-
in the root directory of your working copy.
113+
Or with Docker:
114+
115+
```bash
116+
docker-compose up
117+
```

‎better-code/README.md‎

Lines changed: 0 additions & 52 deletions
This file was deleted.

0 commit comments

Comments
 (0)