The documentation for users of the HMPPS Tech Team services.
It's built using the GDS Tech Docs Template, and hosted using GitHub Pages.
Preview changes locally by running this command:
make preview
This will run a preview web server on http://localhost:4567
This is only accessible on your computer, and won't be accessible to anyone else.
To make changes, create a branch and edit the appropriate Markdown
and ERB files in the source
directory.
Every change should be reviewed in a pull request, no matter how minor, and we've enabled branch protection to enforce this.
GDS Tech Docs (and therefore this site) uses kramdown for its Markdown processing.
Every page of the site needs a source/[page name].html.md.erb
file.
This file lists the partials which comprise the page, in the
order in which they should appear. By convention, all such
partials are in the source/documentation
directory.
These source/[page name].html.md.erb
files have a 'weight' attribute
which determines the order in which they will appear. Higher weights
are further down in the list.
For more information, see the Tech Docs Template documentation for a basic multipage site.
There is a Github Action which will publish your
changes automatically, when your branch is merged into main
The markdown files in the source
directory are compiled to HTML, and the
resulting files are pushed to a second repository from where they are
published via Github Pages.
So, you should not need to do anything else in order to update the user guide website.
The github action is defined in .github/workflows/publish.yml
The publishing process automatically checks both internal and external links in the site. If you want to do the same check locally, run:
make check
If you need to make any changes to the docker image (i.e. if you make any changes to the Dockerfile or Gemfile), please use the github web interface to create a new release. A github action will build the docker image and push it to docker hub, tagged with the release number.
After changing the tag, you need to update the reference to the image in
.github/workflows/publish.yml
and the makefile
.