Repository: data-community-tech-docs

Data Community Technical Documentation

GitHub: data-community-tech-docs
Ownership: #govuk-insights-and-analytics-team owns the repo. #insights-and-analytics-alerts receives automated alerts for this repo.
Category: Utilities
Links: Sentry (error tracking)

README

This project uses the Tech Docs Template, which is a Middleman template that you can use to build technical documentation using a GOV.UK style.

👉 To find out more about setting up and managing content for a website using this template, see the Tech Docs Template documentation.

Before you start

To use the Tech Docs Template you need:

The tech docs template documentation says to install the latest 2.7.x version listed at https://www.ruby-lang.org/en/downloads/ which is 2.7.8, but that page says that 2.7.8 is no longer maintained, and rbenv will only install 2.7.6. The documentation also says to use RVM to install Ruby, but the GDS Way recommends rbenv.

Create a new website

Install rbenv
Install Ruby version 2.7.6 rbenv install 2.7.6
Activate Ruby version 2.7.6 in your current terminal rbenv shell 2.7.6
Install an old version of a dependency rbenv exec gem install contracts -v 0.16.1
Install middleman rbenv exec gem install middleman
Use middleman to create a new website rbenv exec middleman init <folder-name> -T alphagov/tech-docs-template
Change directory into the new website cd <folder-name>
Install packages that the website requires rbenv exec bundle install

Change the contents of the file config.rb to the following

require 'govuk_tech_docs'

GovukTechDocs.configure(self)

configure :build do
  activate :relative_assets
end

Making changes

To make changes to the content of this website, edit files in the source folder of this repository.

You can add content by editing the .html.md.erb files. These files support content in:

Markdown
HTML
Ruby

👉 You can use Markdown and HTML to generate different content types and Ruby partials to manage content.

👉 Learn more about producing more complex page structures for your website.

Preview your changes locally

In your terminal:

make init
make local-dev

👉 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.

Build

To build the HTML pages from content in your source folder, run:

rbenv exec 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.

Troubleshooting

Do not run bundle update because the website only builds with the current package versions, given the old version of ruby. You could try using a more recent version of ruby, and recent versions of all the packages.

Run rbenv exec bundle exec middleman build --verbose to get detailed error messages to help with finding the problem.

Licence

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.