The HMCTS Way

Source for The HMCTS Way — technical documentation for engineering teams across HMCTS (His Majesty's Courts and Tribunals Service).

Getting started

There are two ways to run this site locally: GitHub Codespaces (no setup required) or a local installation.

GitHub Codespaces

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.

Local installation

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 terminal

2. Install dependencies

gem install bundler
bundle install

Making changes

Edit the source files in the source folder. Each section of the site is an .html.md.erb file.

Adding content to an existing page

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' %>

Diagrams

Mermaid rendering has been added to this site - this means if you use Mermaid you do not have to export it into a non-editable image form before displaying it.

It also means you are now able to edit the diagrams directly from the local development execution of this documentation site if you wish so, although you may wish to use Mermaid preview anyway as it offers faster refresh.

To render your Mermaid diagram on any documentation page simply create a Mermaid diagram file within the diagrams directory:

- diagrams
  - diagram.mmd

Then add a mermaid pre-tag and load the file contents within it, this has been done to avoid polluting the text only pages with long mermaid code:

<pre class="mermaid">
<%= File.read(File.join(File.dirname(current_page.source_file), 'images', 'diagram.mmd')) %>
</pre>

This will render your diagram wherever you placed it on the page.

It can be clicked to switch the view to full-screen and you can pan around by dragging with the mouse and zoom-in with the scroll-wheel/mouse pad.

Adding a new page

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.

Preview

Start a local server that auto-reloads when you save changes:

bundle exec middleman server

Then open http://localhost:4567 in your browser.

Build

To generate static HTML files (e.g. to publish without a build script):

bundle exec middleman build

This creates a build folder containing the compiled HTML and assets.

Publishing

bundle exec rake publish