govuk_tech_docs 6.2.4 → 6.3.0

data/{example → documentation}/config.rb

@@ -1,12 +1,9 @@
 require "govuk_tech_docs"
 
-GovukTechDocs.configure(self)
-
-ignore "templates/*"
+set :relative_links, true
+activate :relative_assets
 
-proxy "/a-proxied-page.html", "templates/proxy_template.html", locals: {
-  title: "I am a title",
-}
+GovukTechDocs.configure(self)
 
 gem_root = File.expand_path("..", __dir__)
 files.watch :reload, path: File.join(gem_root, "lib")

data/documentation/source/accessibility/index.html.md.erb

@@ -0,0 +1,64 @@
+---
+title: Accessibility statement for Technical Documentation Template and documentation
+last_reviewed_on: 2021-10-06
+review_in: 6 months
+hide_in_navigation: true
+---
+
+# Accessibility
+
+The GOV.UK Technical Documentation Template and its documentation are maintained by the technical writing team at the Government Digital Service (GDS).
+
+## Accessibility statement for the Technical Documentation Template documentation website
+
+This accessibility statement applies to the documentation at [https://alphagov.github.io/tech-docs-gem](https://alphagov.github.io/tech-docs-gem/).
+
+This website is run by GDS. We want as many people as possible to be able to use this website. For example, that means you should be able to:
+
+- change colours, contrast levels and fonts
+- zoom in up to 300% without problems
+- navigate most of the website using just a keyboard
+- navigate most of the website using speech recognition software
+- listen to most of the website using a screen reader (including the most recent versions of JAWS, NVDA and VoiceOver)
+
+We’ve also made the website text as simple as possible to understand.
+
+[AbilityNet](https://mcmw.abilitynet.org.uk/) has advice on making your device easier to use if you have a disability.
+
+### How accessible this website is
+
+This website is fully compliant with the [Web Content Accessibility Guidelines version 2.1](https://www.w3.org/TR/WCAG21/) AA standard.
+
+#### Feedback and contact information
+
+If you need information on this website in a different format like accessible PDF, large print, easy read, audio recording or braille, email [technical-writers@digital.cabinet-office.gov.uk](mailto:technical-writers@digital.cabinet-office.gov.uk).
+
+We’ll consider your request and get back to you in 3 working days.
+
+##### Reporting accessibility problems with this website
+
+We’re always looking to improve the accessibility of this website. If you find any problems not listed on this page or think we’re not meeting accessibility requirements, email [technical-writers@digital.cabinet-office.gov.uk](mailto:technical-writers@digital.cabinet-office.gov.uk).
+
+##### Enforcement procedure
+
+The Equality and Human Rights Commission (EHRC) is responsible for enforcing the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018 (the ‘accessibility regulations’). If you’re not happy with how we respond to your complaint, [contact the Equality Advisory and Support Service (EASS)](https://www.equalityadvisoryservice.com/).
+
+#### Technical information about this website’s accessibility
+
+##### Compliance status
+
+This website is fully compliant with the [Web Content Accessibility Guidelines version 2.1](https://www.w3.org/TR/WCAG21/) AA standard.
+
+### Preparation of this accessibility statement
+
+This statement was prepared on 2 September 2020. It was last reviewed on 6 October 2021.
+
+This website was last tested in April 2021.
+
+## Using the Technical Documentation Template for your own documentation
+
+This [Technical Documentation Template](https://github.com/alphagov/tech-docs-template) was last tested in April 2021. The test was carried out by the [Digital Accessibility Centre (DAC)](https://digitalaccessibilitycentre.org/).
+
+While GDS takes steps to ensure the Technical Documentation Template is as accessible as possible by default, you’ll still need to make sure your documentation as a whole meets accessibility requirements. You must research your documentation content to ensure that it’s in context.
+
+Find out what you need to do to [make your service accessible](https://www.gov.uk/service-manual/helping-people-to-use-your-service/making-your-service-accessible-an-introduction) in the GOV.UK Service Manual.

data/documentation/source/configure_project/frontmatter/index.html.md.erb

@@ -0,0 +1,206 @@
+---
+title: Configure page settings
+weight: 34
+last_reviewed_on: 2020-07-01
+review_in: 1 year
+---
+
+# Configure page settings
+
+You configure individual pages in your documentation by editing the page frontmatter.
+
+The page frontmatter contains page-specific variables at the top of the page.
+
+For a general introduction on frontmatter, see the [Middleman frontmatter documentation][mm].
+
+For example:
+
+```html
+---
+title: Page title
+weight: 100
+last_reviewed_on: 2100-01-01
+review_in: 1 year
+---
+
+# Configure page settings
+
+You configure individual pages in your documentation by editing the page frontmatter.
+```
+
+<%= warning_text('You should enable or disable settings to increase the usability of your documentation or because of best practice.') %>
+
+If you are not sure which settings to enable or disable, [contact the GDS tech writers][contact-email].
+
+## Required frontmatter settings
+
+There are no required frontmatter settings in a single page documentation site.
+
+In a multipage documentation site, you must include the weight frontmatter setting.
+
+### weight
+
+Sets the order of pages in the left hand navigation.
+
+This setting works the same way as page numbers in a book. A lower weight value is higher in the navigation. A higher weight value is lower in the navigation.
+
+For example a page with a weight of 10 will appear higher in the navigation than a page with a weight of 20.
+
+```yaml
+---
+weight: 20
+---
+```
+
+## Optional frontmatter settings
+
+You can enable and disable the following optional settings in the page frontmatter.
+
+### description
+
+Sets the description for the page, which will be used in search engine results or on social media.
+
+```yaml
+---
+description: Configuring page settings in the GDS Technical Documentation Template.
+---
+```
+
+### hide_in_navigation
+
+Set `hide_in_navigation: true` to prevent the page from being rendered in the main left hand navigation.
+
+```yaml
+---
+hide_in_navigation: true
+---
+```
+
+### "last_reviewed_on" and "review_in"
+
+These attributes determine the date when the page needs to be reviewed next.
+
+See [page expiry and review documentation][expiry] for more details.
+
+You can use this in combination with the [owner_slack variable](#owner-slack) to set an owner for the page.
+
+### layout
+
+The layout of the page. By default, pages will use the `layout` layout. This layout will parse the page and generate a sidebar with a table of contents consisting of each `h2`, `h3`, `h4` heading.
+
+```md
+---
+layout: layout
+---
+
+# The title
+
+## A subheader
+
+### A h3 subheader
+
+## Another subheader
+```
+
+This layout generates a page with the headings from the content in the sidebar.
+
+If you want more control about the layout, you can use the `core` layout. This allows you to specify the sidebar manually with a `content_for` block.
+
+```rb
+---
+layout: core
+---
+
+<%% content_for :sidebar do %>
+  You can put anything in the sidebar.
+<%% end %>
+
+This page has a configurable sidebar that is independent of the content.
+```
+
+If you do not specify a sidebar, you get a one-column layout without a sidebar.
+
+```rb
+---
+layout: core
+---
+
+This page does not have a sidebar.
+```
+
+You can use layouts to group pages and customise your Table of Contents (ToC).  To create a layout, create a new ruby file in the `source/layouts` directory, for example `source/layouts/live_support.erb`.  
+
+Apply the template by including it in the frontmatter block of a page. In this example, we're applying the `live_support` layout to the page:
+
+```rb
+---
+layout: live_support
+---
+```
+
+The `tech-docs-gem` also has [helper functions you can use to manage your Table of Contents](https://github.com/alphagov/tech-docs-gem?tab=readme-ov-file#table-of-contents-helper-functions).
+
+### old_paths
+
+Any paths of pages that should redirect to this page.
+
+Example:
+
+```yaml
+---
+old_paths:
+  - /some-old-page.html
+---
+```
+
+### owner_slack
+
+The Slack username or channel of the page owner. Use this to appoint an individual or team as responsible for keeping the page up to date.
+
+```yaml
+---
+owner_slack: "#operations-teams"
+---
+```
+
+### parent
+
+Defines the page that should be highlighted as ‘active’ in the navigation.
+
+```yaml
+---
+parent: shaving-yaks.html
+---
+```
+
+### prevent_indexing
+
+Set `prevent_indexing: true` to prevent the page from being indexed by search engines.
+
+```yaml
+---
+prevent_indexing: true
+---
+```
+
+### source_url
+
+If the contribution banner is turned on, you can override the "View source" link using `source_url`.
+
+Example:
+
+```yaml
+source_url: http://example.org/source.md
+```
+
+### title
+
+The browser title of the page.
+
+```yaml
+---
+title: My beautiful page
+---
+```
+
+<%= partial "partials/links" %>

data/documentation/source/configure_project/global_configuration/index.html.md.erb

@@ -0,0 +1,328 @@
+---
+title: Configure your documentation site
+weight: 31
+last_reviewed_on: 2020-07-01
+review_in: 1 year
+---
+
+# Configure your documentation site
+
+You can configure your documentation site by editing the `config/tech-docs.yml` file in a text editor.
+
+When you create your documentation project, the template creates a `tech-docs.yml` file with the following default settings:
+
+```yaml
+# Host to use for canonical URL generation (without trailing slash)
+host:
+
+# Header-related options
+show_govuk_logo: true
+service_name: My First Service
+service_link: https://www.larry-the-cat.service.gov.uk
+phase: Beta
+
+# Uncomment if you do not want to activate the GOV.UK Design System component extension 
+# enable_govuk_components: false
+
+# Links to show on right-hand-side of header
+header_links:
+  About: https://www.larry-the-cat.service.gov.uk
+  Get Started: https://www.larry-the-cat.service.gov.uk/get-started
+  Documentation: /
+  Support: https://www.larry-the-cat.service.gov.uk/support
+
+# Enables search functionality. This indexes pages only and is not recommended for single-page sites.
+enable_search: false
+
+# Tracking ID from Google Analytics (for example UA-XXXX-Y)
+ga_tracking_id:
+
+# Enable multipage navigation in the sidebar
+multipage_nav: false
+
+# Enable collapsible navigation in the sidebar
+collapsible_nav: false
+
+# Table of contents depth – how many levels to include in the table of contents.
+# If your ToC is too long, reduce this number and we'll only show higher-level
+# headings.
+max_toc_heading_level: 6
+
+# Prevent robots from indexing (for example whilst in development)
+prevent_indexing: false
+
+show_contribution_banner: true
+github_repo: alphagov/YOUR_REPO
+github_branch: main
+```
+
+<%= warning_text('All of these settings are optional. However, you should enable or disable settings to increase the usability of your documentation or because of best practice.') %>
+
+You must wrap a value in quotes if it contains a colon, unless the value is a URL. For example:
+
+```
+description: "GDS: My amazing documentation"
+```
+
+If you are not sure which settings to enable or disable, [contact the Government Digital Service (GDS) technical writing team][contact-email].
+
+See the [Platfom as a Service (PaaS) tech docs config file][global-config-example] for an example `tech-docs.yml` file.
+
+## Default settings
+
+The following section defines the default settings in the `tech-docs.yml` file, and tells you how to enable and disable them.
+
+### host
+
+Defines the host used for canonical URL generation (without trailing slash).
+
+```yaml
+host: https://docs.cloud.service.gov.uk
+```
+
+### show_govuk_logo
+
+Enables and disables the GOV.UK crown logo in the top left corner of the site. Defaults to `true`.
+
+```yaml
+show_govuk_logo: true
+```
+
+### service_name
+
+Defines the service name in the header. Defaults to "My First Service" if you do not define it when creating your project.
+
+```yaml
+service_name: "Platform as a Service"
+```
+
+### service_link
+
+What the service name in the header links to. Defaults to "https://www.larry-the-cat.service.gov.uk" if you do not define it when creating your project.
+
+```yaml
+service_link: "https://www.larry-the-cat.service.gov.uk"
+```
+
+### phase
+
+Defines the phase of the service that the documentation is attached to. Defaults to "Beta".
+
+```yaml
+phase: "Beta"
+```
+
+### enable_govuk_components
+
+The `tech-docs-gem` contains a custom extension to allow you to use [GOV.UK Design System components](https://design-system.service.gov.uk/components).  You can include these in your content by creating a `ruby` codeblock, and calling the component as described in the GOV.UK Design System documentation.  For example, you can include a [GOV.UK Button](https://design-system.service.gov.uk/components/button/):
+
+```markdown
+
+# My heading
+
+This would be a short introduction, but now we need a button!
+
+
+<%%= govukButton({
+  text: "Click me!"
+}) %>
+
+
+Phew, lucky we had that component available!
+
+```
+
+You do not need to import the function using `from "govuk/components/{COMPONENT_NAME}/macro.njk" import {COMPONENT_NAME}`.  The extension will do this automatically.
+
+
+### header_links
+
+Populates the top right banner navigation with links. You can change the number and text of the default links. For example:
+
+```yaml
+header_links:
+  About: https://www.payments.service.gov.uk/#main
+  Get started: https://www.payments.service.gov.uk/getstarted/
+  Documentation: /
+  Support: https://www.payments.service.gov.uk/support/
+  Sign In: https://selfservice.payments.service.gov.uk/login
+```
+### enable_search
+
+Enables search functionality. This indexes pages only, and you should only enable this if you have a multipage documentation site.
+
+```yaml
+enable_search: true
+```
+
+### ga_tracking_id
+
+Insert the Google Analytics tracking ID to enable Google Analytics.
+
+If you use Google Analytics, you must follow [the guidance on working with cookies](https://www.gov.uk/service-manual/technology/working-with-cookies-and-similar-technologies) in the GOV.UK Service Manual.
+
+Speak to your technical or engineering community to find out how to enable Google Analytics for your documentation and get a tracking ID.
+
+```yaml
+ga_tracking_id: UA-XXXX-Y
+```
+
+### multipage_nav
+
+Enable multipage navigation in the sidebar. Defaults to `false`.
+
+```yaml
+multipage_nav: false
+```
+
+### collapsible_nav
+
+Enable collapsible navigation in the sidebar. Defaults to `false`.
+
+```yaml
+collapsible_nav: false
+```
+
+### max_toc_heading_level
+
+States how many heading levels to include in the table of contents (ToC). Can take values between 1 and 6. Use a lower number to reduce the length of the ToC. Best practice is to not go higher than 3.
+
+```yaml
+max_toc_heading_level: 6
+```
+
+### prevent_indexing
+
+Prevent robots from indexing.
+
+```yaml
+prevent_indexing: false
+```
+
+### show_contribution_banner
+
+Enable a banner at the bottom of the page that links to the page source, so readers can easily contribute back to the documentation. Defaults to "true".
+
+If you enable this setting, you must also enable the [github_repo] setting.
+
+```yaml
+show_contribution_banner: true
+```
+
+### github_repo
+
+Your documentation project's GitHub repository. You must enable this if you have enabled [show_contribution_banner].
+
+```yaml
+github_repo: alphagov/example-repo
+```
+
+### github_branch
+
+Your project's GitHub default branch name. You can change this if your default branch is not named main.
+
+```yaml
+github_branch: source
+```
+
+Note: When creating a project using the template this is set to "main", but if this setting is not present the default is currently "master". This will change in a future major release.
+
+## Additional settings
+
+You can enable and disable the following additional settings in the `tech-docs.yml` file.
+
+### api_path
+
+Define a path to an [Open API V3 spec file][openapi3]. This can be a relative file path or a URI to a raw file.
+
+```yaml
+api_path: ./source/pets.yml
+```
+
+### footer_links
+
+Defines links to show in the site footer.
+
+```yaml
+footer_links:
+  Accessibility: /accessibility
+```
+
+### full_service_name
+
+The full service name. Include "GOV.UK" if appropriate.
+
+```yaml
+full_service_name: "GOV.UK Pay"
+```
+
+### google_site_verification
+
+Adds a [Google Site verification code] to the meta tags.
+
+```yaml
+google_site_verification: TvDTuyvdstyusadrCSDrctyd
+```
+
+### "owner_slack_workspace" and "default_owner_slack"
+
+These attributes are used to specify the owner of a page.  See [page expiry][expiry] for more information.
+
+### redirects
+
+A list of redirects from an old location to a new location.
+
+Use this to set up external redirects or if [setting `old_paths` in the frontmatter][old-paths] does not work.
+
+```yaml
+redirects:
+  /old-page.html: https://example.org/something-else.html
+  /another/old-page.html: /another/new-page.html
+```
+
+### show_expiry
+
+Enables and disables displaying a red banner when the page needs to be reviewed.
+
+If not present or set to `true`, the red banner will display when the page needs to be reviewed. This is the default behaviour.
+
+If set to `false`, the red banner will not display when the page needs to be reviewed.
+
+See [page expiry][expiry] for more information.
+
+
+### show_review_banner
+
+Enables or disables displaying the page review banner, regardless of whether the page needs to be reviewed or not.
+
+If not present or set to `true`, the banner will always be displayed on the page. This is the default behaviour.
+
+If set to `false`, the banner will not be displayed.
+
+See [page expiry][expiry] for more information.
+
+### source_urls
+
+If you've [enabled the contribution banner][show_contribution_banner], set source_urls to the URLs you want the contribution banner to link to.
+
+By default, "Report issue" links to raising a GitHub issue, but by modifying the `report_issue_url`, it can link to an email address or another page.
+
+```yaml
+source_urls:
+  report_issue_url: mailto:support@example.com
+```
+
+## Build your site using relative links
+
+You can configure the Technical Documentation Template (TDT) to build your documentation site using relative links to pages and assets.
+
+To use relative links, add the following lines to your `config.rb` file:
+
+```
+set :relative_links, true
+activate :relative_assets
+```
+
+
+
+<%= partial "partials/links" %>

data/documentation/source/configure_project/index.html.md.erb

@@ -0,0 +1,17 @@
+---
+title: Configure your documentation project
+weight: 30
+last_reviewed_on: 2020-07-01
+review_in: 1 year
+---
+
+# Configure your documentation project
+
+You can change your documentation project by:
+
+- [changing the site configuration options][global-config]
+- [structuring your documentation][structure-your-docs] to be single or multipage
+- configuring individual page settings using [page frontmatter][frontmatter]
+- [setting an expiration date][expiry] for a page
+
+<%= partial "partials/links" %>