BAT tech team guide
This is the repo for the Teacher Services tech docs.
The required versions of build tools are defined in .tool-versions. These can be automatically installed with asdf-vm, see their installation instructions.
Install the plugin specified in .tool-versions
asdf plugin add rubyasdf install
(We don’t mandate asdf, you can use other tools if you prefer.)
Copy .env.example to .env and populate a GitHub token with read access to repos.
To preview your new website locally, navigate to your project folder and run:
bundle exec middleman server
👉 See the generated website on http://localhost:4567 in your browser. Any content changes you make to your website will be updated in real time.
To shut down the Middleman instance running on your machine, use ctrl+C.
If you make changes to the config/tech-docs.yml configuration file, you need to restart Middleman to see the changes.
To build the HTML pages from content in your source folder, run:
bundle exec middleman build
Every time you run this command, the build folder gets generated from scratch. This means any changes to the build folder that are not part of the build command will get overwritten.
The site is deployed automatically to the AKS production cluster whenever main branch is updated.
Run bundle update to make sure you’re using the most recent Ruby gem versions.
Run bundle exec middleman build --verbose to get detailed error messages to help with finding the problem.
Unless stated otherwise, the codebase is released under the MIT License. The documentation is © Crown copyright and available under the terms of the [Open Government 3.0][ogl] licence.