Source for The HMCTS Way — technical documentation for engineering teams across HMCTS (His Majesty's Courts and Tribunals Service).
There are two ways to run this site locally: GitHub Codespaces (no setup required) or a local installation.
GitHub Codespaces gives you a ready-to-use dev environment in your browser with no local setup needed. The dev container installs all dependencies automatically, this can take a few minutes on first load.
The container starts the preview server itself. Once setup is complete, open the Ports panel, hover over the forwarded address for port 4567 to reveal the globe icon, and open the site from there.
Prerequisites: macOS ships with an old system Ruby that won't work here. You need the version specified in .ruby-version, managed via rbenv.
1. Install rbenv and the required Ruby version
brew install rbenv ruby-build
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc
rbenv install # reads the version from .ruby-version automatically
rbenv rehash # makes the new ruby commands available in your terminal2. Install dependencies
gem install bundler
bundle installEdit the source files in the source folder. Each section of the site is an .html.md.erb file.
Content is split across multiple markdown files and manually included in source/index.html.md.erb. To add a new file (e.g. source/documentation/agile/scrum.md), add this line in the appropriate place in that file:
<%= partial 'documentation/agile/scrum' %>
Create a file with a .html.md extension anywhere in the source directory. For example, source/about.html.md will be served at http://localhost:4567/about.html.
Start a local server that auto-reloads when you save changes:
bundle exec middleman serverThen open http://localhost:4567 in your browser.
To generate static HTML files (e.g. to publish without a build script):
bundle exec middleman buildThis creates a build folder containing the compiled HTML and assets.
bundle exec rake publish