govuk_tech_docs 6.3.0.beta → 6.3.0

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" %>

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

@@ -0,0 +1,93 @@
+---
+title: Set review date for pages
+weight: 35
+last_reviewed_on: 2020-07-01
+review_in: 1 year
+---
+
+# Set review date for pages
+
+It's possible to include frontmatter configuration for a page to set an
+expiration date for a piece of content. The expiration date is calculated using the `last_reviewed_on` and `review_in` frontmatter configuration parameters.
+
+The `show_expiry` parameter in the global configuration file decides if the banners at the bottom of the page say that the page is expired or not.
+
+For `show_expiry: true`, the banner at the bottom turns red if it's past the expiration date.
+
+If the page doesn't need to be reviewed, we show a blue box with the
+last-reviewed date, when it needs review again, and the owner.
+
+<%= image_tag "/images/not-expired-page.png", { :alt => 'Banner that shows that page is not expired' } %>
+
+If the page needs to be reviewed, we show a red box saying the page might not
+be accurate.
+
+<%= image_tag "/images/expired-page.png", { :alt => 'Banner that shows that page is expired' } %>
+
+Setting `show_expiry: false` generates a blue banner with the last reviewed date. This banner stays the same whether the page needs to be reviewed or not.  The banner does not mention when the page needs to be reviewed next or who the owner is.
+
+<%= image_tag "/images/last-reviewed-only.png", { :alt => 'Banner that shows that page needs review' } %>
+
+This feature relies on JavaScript being enabled on the user's browser to
+display the relevant notices.
+
+If you want to disable the banners, but keep the review dates in the frontmatter, add the following to your global configuration file:
+
+```yaml
+show_review_banner: false
+```
+
+The page review banner will no longer appear at the bottom of the page, but Daniel the Manual Spaniel will still notify you about expired pages.
+
+## Frontmatter configuration
+
+### `last_reviewed_on` and `review_in`
+
+These attributes determine the date when the page needs to be reviewed next.
+
+```yaml
+---
+last_reviewed_on: 2018-01-18
+review_in: 6 weeks
+---
+```
+
+You can use this in combination with `owner_slack` or `default_owner_slack` to
+set an owner for the page.
+
+### `owner_slack`
+
+The Slack username or channel of the page owner. This can be used to appoint an
+individual or team as responsible for keeping the page up to date.
+
+
+## Global configuration
+
+### `owner_slack_workspace`
+
+The Slack workspace name used when linking to the Slack owner of a piece of
+content. If not provided, the owner of a piece of content (channel or user)
+won't be linked.
+
+```yaml
+owner_slack_workspace: gds
+```
+
+### `default_owner_slack`
+
+The default Slack user or channel name to show as the owner of a piece of
+content. Can be overridden using the `owner_slack` frontmatter config option.
+
+```yaml
+default_owner_slack: '#owner'
+```
+
+
+## Page API
+
+The expiry date for each page is also shown in the `/api/pages.json`
+representation of all pages.  This is used by the
+[page expiry notifier][daniel-github] to post
+messages to Slack when pages have expired.
+
+<%= partial "partials/links" %>