govuk_tech_docs 6.6.0.rc.local.tested → 6.6.0

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

@@ -1,386 +0,0 @@
----
-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
-product_name: GOV.UK Product
-show_govuk_logo: true
-service_name: My First Service
-service_link: https://www.larry-the-cat.service.gov.uk
-phase: Beta
-
-#These can be used to add custom classes to the GOV.UK header, footer and service navigation components. You can find more detail about these on the component documentation at:
-#https://design-system.service.gov.uk/components/header/
-#https://design-system.service.gov.uk/components/service-navigation/
-#https://design-system.service.gov.uk/components/footer/
-
-headerContainerClasses:
-headerClasses:
-navigationContainerClasses:
-navigationClasses:
-footerContainerClasses:
-footerClasses:
-
-# 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
-```
-
-<%= govukWarningText({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.", iconFallbackText: "Warning"}) %>
-
-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
-```
-
-<%= govukWarningText({text: "This setting is deprecated and will be replaced in version 7 by the generic header and custom logo options.", iconFallbackText: "Warning"}) %>
-
-### product_name
-
-Used for the `productName` value in the [GOV.UK header component](https://design-system.service.gov.uk/components/header/).  It is used when the product name follows on directly from ‘GOV.UK’. For example, GOV.UK Pay or GOV.UK Design System. In most circumstances, you should use the Service navigation component.
-
-```yaml
-product_name: "Great new product"
-```
-
-
-
-### 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"
-```
-
-### Header and footer custom styles
-
-If you have set `show_gouk_logo` to `true`, the header, service navigation and footer will use GOV.UK components.
-
-#### Container classes
-
-Classes for the container, useful if you want to make the header fixed width. The container settings you can configure are:
-
-- `headerContainerClasses:`
-- `navigationContainerClasses:`
-- `footerContainerClasses:`
-
-```yaml
-headerContainerClasses: "my-custom-container-style my-additional-styles"
-```
-
-You can add custom classes to the components in the same way.  The settings you can configure are:
-
-- `headerClasses:`
-- `navigationClasses:`
-- `footerClasses:`
-
-```yaml
-footerClasses: "my-custom-footer-style"
-```
-
-There is more detail on the [GOV.UK Design System](https://design-system.service.gov.uk/components) documentation site.
-
-### 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 configure this if you have enabled [show_contribution_banner].
-
-Set this to either the repository's `owner/name` or its full GitHub URL. Link to the repository itself, rather than a file or directory, because the contribution banner builds its links relative to this URL.
-
-```yaml
-github_repo: alphagov/example-repo
-```
-
-You can also use the full URL:
-
-```yaml
-github_repo: https://github.com/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

@@ -1,17 +0,0 @@
----
-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

@@ -1,93 +0,0 @@
----
-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" %>

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

@@ -1,117 +0,0 @@
----
-title: Structure your documentation
-weight: 32
-last_reviewed_on: 2020-07-01
-review_in: 1 year
----
-
-# Structure your documentation
-
-When you [create a new project][create-project], that project has a source folder containing:
-
-- a `documentation/index.md` content file
-- an `index.html.md.erb` file
-
-The `index.html.md.erb` file contains a `partial` that refers to the `documentation/index.md` content file.
-
-To structure your documentation, add content directly to the `index.html.md.erb` file.
-
-For example, an `index.html.md.erb` file with the following sections:
-
-- an introduction
-- a "Who this documentation is for" section
-- a "Set up the API client" section
-
-That `index.html.md.erb` file could look like this:
-
-```html
----
-title: Tech Docs
----
-
-# Introduction
-
-CONTENT
-
-# Who is this documentation for?
-
-CONTENT
-
-# Set up the API client
-
-CONTENT
-
-```
-
-When you build or preview your documentation site with this `index.html.md.erb`, the site will be a single page site with the following structure:
-
-- Introduction
-- Who is this documentation for?
-- Set up the client
-
-## Build a multipage documentation site
-
-You can create a technical documentation site that splits its content across multiple pages.
-
-This is suitable for documentation sites that have too much content for the single page format.
-
-Examples include the:
-
-- [GOV.UK Platform as a Service (PaaS) technical documentation][paas-docs]
-- [GOV.UK Pay technical documentation][pay-docs]
-
-You should [use the search feature][search-feature] with multipage documentation sites.
-
-### Amend the tech-docs.yml file
-
-Add the following code to your project’s `config/tech-docs.yml` file if necessary:
-
-```yaml
-multipage_nav: true
-```
-
-### Create the multipage folder structure
-
-Each folder inside the `source` folder represents one documentation page.
-
-For each page, create a content folder and put an `index.html.md.erb` file into that folder. This `index.html.md.erb` file is the [content file][write-content].
-
-### Amend the index.html.md.erb files
-
-Add a weight argument and value to the frontmatter of each .html.md.erb file. This builds the structure of the multipage documentation.
-
-For example:
-
-```yaml
----
-title: Product Technical Documentation
----
-```
-
-becomes
-
-```yaml
----
-title: Product Technical Documentation
-weight: 10
----
-```
-
-Higher weights mean the content is lower down in the documentation hierarchy. A way to remember this is to think “heavier pages sink to the bottom”.
-
-Make sure every individual page starts with an H1 heading.
-
-### Nest pages within pages (optional)
-
-You can nest pages within each other.
-
-To do this, create content folders inside content folders with `index.html.md.erb` content files.
-
-Each `.html.md.erb` file inside a nested folder must have a weight value that preserves the overall hierarchy both within the nested content and compared to the other non-nested content.
-
-An example of this content structure is the GOV.UK Pay technical documentation on switching to live:
-
-- [documentation pages][nested-example]
-- [GitHub folder][nested-example-code]
-
-<%= partial "partials/links" %>

data/documentation/source/create_project/build/index.html.md.erb

@@ -1,20 +0,0 @@
----
-title: Build your documentation
-weight: 24
-last_reviewed_on: 2021-07-01
-review_in: 1 year
----
-
-# Build your documentation
-
-1. Open the command line interface and go to your documents folder.
-
-2. Run the following in the command line:
-
-    ```shell
-    bundle exec middleman build
-    ```
-
-This will create HTML documentation files in the `source/build` folder.
-
-<%= partial "partials/links" %>

data/documentation/source/create_project/create_new_project/index.html.md.erb

@@ -1,23 +0,0 @@
----
-title: Create a new documentation project
-weight: 22
-last_reviewed_on: 2021-07-01
-review_in: 1 year
----
-
-# Create a new documentation project
-
-1. Open the command line interface and go to your documents folder.
-
-2. Run the following in the command line:
-
-    ```shell
-    middleman init <project_name> -T alphagov/tech-docs-template
-    ```
-    where `<project_name>` is the name of your project.
-
-3. Answer the installation questions.
-
-4. When you see `Bundle complete!`, go to the new project folder and run `bundle install` to update the Ruby gems.
-
-<%= partial "partials/links" %>