Tech Docs Template - gem

This repo contains the Ruby gem that distributes the Tech Docs Template. The Tech Docs Template 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.

Contributing

Everybody who uses this project is encouraged to contribute.

Find out how to contribute.

GOV.UK frontend

This gem uses GOV.UK Frontend, part of the GOV.UK Design System.

We use npm to download the govuk-frontend package. To update to a new version, change the version in the package.json file and run npm update.

Table of contents helper functions

With Middleman you can apply layouts to group pages and customise sites. This gem has the following additional helper functions to manage the table of contents (ToC):

single_page_table_of_contents to create a ToC from the headings on the current page
multi_page_table_of_contents to create a ToC for a group of pages, opened at the current page

Single page table of contents

The single_page_table_of_contents helper has the following parameters:

Parameter	Description
`html`	The html of the current page.
`url`	Optional parameter used to override the url of the page heading. Defaults to `""`.
`max_level`	Optional parameter used to set the depth of the table of contents. Defaults to `nil`.

Below is an example of using single_page_table_of_contents in a layout file:

<%
wrap_layout :core do
  content_for :sidebar do
      <%= single_page_table_of_contents(html, max_level: 2) %>
  end
end
%>

This example will create a ToC containing the current page title, and nested headings to a depth of 2.

Multi page table of contents

The multi_page_table_of_contents has the following parameters:

Parameter	Description
`resources`	An array of middleman site resources for the pages to be included in the ToC.
`current_page`	The resource object found in the middleman current_page.
`config`	Site settings defined in `/config/tech-docs.yaml`.
`current_page_html`	Optional html of the current page. Defaults to `nil`.
`include_child_resources`	Optional setting used to include child resources when creating a ToC. Defaults to `true`.

Below is an example of using multi_page_table_of_contents in a layout file:

<%
wrap_layout :core do
  content_for :sidebar do
      <%= multi_page_table_of_contents(sitemap.resources, current_page, config, yield, include_child_resources: true) %>
  end
end
%>

This example will create a ToC containing the page title of each resource, as a heading. Each heading can be expanded to show nested headings to the depth defined in the site config. If include_child_resources is set to true, child resources will also be included.

Developing locally

There are 2 ways to develop with this gem. You can see your changes on either:

your own Tech Docs Template website
the example in this repository

Use your own Tech Docs Template website

To see how your changes to the gem affect your website, point your website's Gemfile to your local checkout:

gem 'govuk_tech_docs', path: '../tech-docs-gem'

To preview your documentation changes locally, see the Tech Docs Template documentation on previewing your documentation.

If you experience the FFI gem issue for Mojave users, you should refer to this list of possible fixes.

Use the example in this repo

To start the example in this repo, run:

cd example
bundle install
bundle exec middleman server

See your website on http://localhost:4567 in your browser.

If you experience the FFI gem issue for Mojave users, you should refer to this list of possible fixes.

For more information on previewing your documentation locally, see the Tech Docs template documentation on previewing your documentation.

Tests

This repository contains automated JavaScript tests that use the Jasmine test framework.

You can run these tests and see the results in your browser.

Run bundle exec rake jasmine.
Go to http://localhost:8888 in your browser.

To run the tests and see the results in your terminal, run:

bundle exec rake jasmine:ci

Issue with FFI on OSX Mojave

Users on OSX Mojave (10.14) may get this error when running bundle exec middleman serve on apps that use this gem.

There are 3 possible ways to solve this. From best to worst, you can:

upgrade to macOS 10.15 (Catalina) or higher
tell rubygems not to use the system ffi by running gem install ffi -- --disable-system-libffi in the command line when the error shows
pin the ffi version back to 1.12.2 by editing the Gemfile of your app

Releasing new versions

To release a new version, create a new pull request (PR) that updates version.rb and CHANGELOG.md.

Do not include other changes in your pull request, as this makes it easier to find out what was released when. See an example of a PR for releasing a new version.

Travis will automatically release a new version to Rubygems.org.

Licence

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