diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eb91cc47..a753d94d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,10 @@ Everybody who uses this project is encouraged to contribute to this project. If you're part of the [alphagov GitHub organisation](https://www.github.com/alphagov) you probably have write access to this repo. If you don't, ask a GitHub admin or #tech-docs-format on Slack. - Before adding your feature, [check the backlog to see if someone is already talking about it](https://github.com/alphagov/tech-docs-template/issues) -- If you add a new option to `config/tech-docs.yml`, make sure you [document the option in docs/configuration.md](docs/configuration.md) -- If you add a new option to the page frontmatter, make sure you [document the option in docs/frontmatter.md](docs/frontmatter.md) +- If you add a new option to `config/tech-docs.yml`, make sure you [document the new configuration option][configuration] +- If you add a new option to the page frontmatter, make sure you [document the new frontmatter configuration](docs/frontmatter.md) - You can test your contribution using [unit tests](spec/govuk_tech_docs), [javascript tests](spec/javascripts) or [integration tests](spec/features) - If your change is relevant to the users of the gem, add something to [CHANGELOG](CHANGELOG.md). You don't have to do this if it's just refactoring. Make sure that you include any upgrade instructions. + +[configuration]: https://github.com/alphagov/tdt-documentation/blob/master/source/amend_project/configuration/index.html.md.erb +[frontmatter]: https://github.com/alphagov/tdt-documentation/blob/master/source/frontmatter.html.md.erb diff --git a/docs/configuration.md b/docs/configuration.md index 4884277c..4e7ea024 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,228 +1,3 @@ # Configuration -You can configure the site using `config/tech-docs.yml`. [See the PaaS tech docs for an example](https://github.com/alphagov/paas-tech-docs/blob/master/config/tech-docs.yml). - -These are all the available options: - -## `ga_tracking_id` - -Tracking ID from Google Analytics - -```yaml -ga_tracking_id: UA-XXXX-Y -``` - -## `github_repo` - -Your repository. Required if [show_contribution_banner](#show-contribution-banner) is true. - -```yaml -github_repo: alphagov/example-repo -``` - -## `github_branch` - -Your github branch name. Useful if your default branch is not named master. - -```yaml -github_branch: source -``` - -## `google_site_verification` - -Adds a [Google Site Verification code](https://support.google.com/webmasters/answer/35179?hl=en) to the meta tags. - -```yaml -google_site_verification: TvDTuyvdstyusadrCSDrctyd -``` - -## `enable_search` - -Enables search functionality. This indexes pages only and is not recommended for single-page sites. - -```yaml -enable_search: true -``` - -## `header_links` - -Right hand side navigation. - -Example: - -```yaml -header_links: - Documentation: / -``` - -## `footer_links` - -Links to show in footer. - -Example: - -```yaml -footer_links: - Accessibility: /accessibility -``` - -## `host` - -Host to use for canonical URL generation (without trailing slash). - -Example: - -```yaml -host: https://docs.cloud.service.gov.uk -``` - -## `collapsible_nav` - -Enable collapsible navigation in the sidebar. Defaults to false; - -```yaml -collapsible_nav: true -``` - -## `multipage_nav` - -Enable multipage navigation in the sidebar. Defaults to false; - -```yaml -multipage_nav: true -``` - -## `max_toc_heading_level` - -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. - -```yaml -max_toc_heading_level: 6 -``` - -## `phase` - -```yaml -phase: "Beta" -``` - -## `prevent_indexing` - -Prevent robots from indexing (e.g. whilst in development) - -```yaml -prevent_indexing: false -``` - -## `redirects` - -A list of redirects, from old to new location. Use this to set up external -redirects or if [setting `old_paths` in the frontmatter](docs/frontmatter.md#old_paths) doesn't work. - -```yaml -redirects: - /old-page.html: https://example.org/something-else.html - /another/old-page.html: /another/new-page.html -``` - -## `service_name` - -The service name in the header. - -Example: - -```yaml -service_name: "Platform as a Service" -``` - -## `full_service_name` - -The full service name (maybe with GOV.UK) - -Example: - -```yaml -full_service_name: "GOV.UK Pay" -``` - -## `service_link` - -What the service name in the header links to. - -default: '/' - -```yaml -service_link: "/" -``` - -## `show_contribution_banner` - -Show a block at the bottom of the page that links to the page source, so readers -can easily contribute back to the documentation. If turned on [github_repo](#github-repo) is -required. - -Off by default. - -```yaml -show_contribution_banner: true -github_repo: alphagov/example-repo -``` - -## `source_urls` - -Customise the URLs that the contribution banner links to. Only useful if -[show_contribution_banner](#show_contribution_banner) is turned on. 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 -``` - -## `show_govuk_logo` - -Whether to show the GOV.UK crown logo. - -default: `true` - -```yaml -show_govuk_logo: true -``` - -## `api_path` - -Define a path to an Open API V3 spec file. This can be a relative file path or a URI to a raw file. - -```yaml -api_path: ./source/pets.yml -``` - -## `owner_slack_workspace` and `default_owner_slack` - -These attributes are used to specify the owner of a page. See the separate -[documentation for page expiry][expiry] for more details. - -## `show_expiry` - -Decides whether or not to show a red banner when the page needs to be reviewed. - -If not present or set to `true`, the red banner will appear when the page needs to be reviewed. This is the default behaviour. - -If set to `false`, the red banner will not appear when the page needs to be reviewed. - -See the separate [documentation for page expiry][expiry] for more details. - -[expiry]: https://tdt-documentation.london.cloudapps.digital/page-expiry.html#page-expiry-and-review - -## `show_review_banner` - -Decides whether or not to display 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 be displayed on the page. This is the default behaviour. - -If set to `false`, the banner will not be displayed. - -See the separate [documentation for page expiry][expiry] for more details. - -[expiry]: https://tdt-documentation.london.cloudapps.digital/page-expiry.html#page-expiry-and-review +This content has been moved to . diff --git a/docs/core-layout-without-sidebar.png b/docs/core-layout-without-sidebar.png deleted file mode 100644 index 92c94d24..00000000 Binary files a/docs/core-layout-without-sidebar.png and /dev/null differ diff --git a/docs/core-layout.png b/docs/core-layout.png deleted file mode 100644 index 3725f720..00000000 Binary files a/docs/core-layout.png and /dev/null differ diff --git a/docs/expired-page.png b/docs/expired-page.png deleted file mode 100644 index 9574398e..00000000 Binary files a/docs/expired-page.png and /dev/null differ diff --git a/docs/frontmatter.md b/docs/frontmatter.md index 59e34475..613a58ea 100644 --- a/docs/frontmatter.md +++ b/docs/frontmatter.md @@ -1,156 +1,3 @@ # Available frontmatter -"Frontmatter" allows page-specific variables to be included at the top of a template using YAML. For a general introduction on frontmatter, see the [Middleman frontmatter docs][mm]. - -## `last_reviewed_on` and `review_in` - -These attributes determine the date when the page needs to be reviewed next. -See the separate [documentation for page expiry][expiry] for more details. - -[expiry]: https://tdt-documentation.london.cloudapps.digital/page-expiry.html#page-expiry-and-review - -Example: - -You can use this in combination with [owner_slack](#owner-slack) to set an owner for the page. - -## `layout` - -The layout of the page. - -```yaml ---- -layout: core ---- -``` - -There are 2 available page layouts. - -### The `layout` layout (default) - -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 -``` - -Will generate a page with the headings from the content in the sidebar. - -![](layout-layout.png) - -### `core` layout - -If you want more control about the layout, use `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. -``` - -![](core-layout.png) - -If you do not specify a sidebar, you will get a simple one-column layout without one. - -```rb ---- -layout: core ---- - -This page does not have a sidebar. -``` - -![](core-layout-without-sidebar.png) - -## `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. This can be used to appoint an individual or team as responsible for keeping the page up to date. - -```yaml ---- -owner_slack: "#operations-teams" ---- -``` - -## `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 ---- -``` - -## `weight` - -Affects the order a page is displayed in the sidebar navigation tree. Lower -weights float to the top. Higher weights sink to the bottom. - -```yaml ---- -weight: 20 ---- -``` - -## `hide_in_navigation` - -Set `hide_in_navigation: true` to prevent the page from being rendered in the -main page tree navigation. - -```yaml ---- -hide_in_navigation: true ---- -``` - -## `parent` - -The page that should be highlighted as ‘active’ in the navigation. - -```yaml ---- -parent: shaving-yaks.html ---- -``` - -[mm]: https://middlemanapp.com/basics/frontmatter +This content has been moved to . diff --git a/docs/last-reviewed-only.png b/docs/last-reviewed-only.png deleted file mode 100644 index a31a0f5a..00000000 Binary files a/docs/last-reviewed-only.png and /dev/null differ diff --git a/docs/last-reviewed-only.svg b/docs/last-reviewed-only.svg deleted file mode 100644 index e950b27a..00000000 --- a/docs/last-reviewed-only.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/layout-layout.png b/docs/layout-layout.png deleted file mode 100644 index 13ccd8e4..00000000 Binary files a/docs/layout-layout.png and /dev/null differ diff --git a/docs/not-expired-page.png b/docs/not-expired-page.png deleted file mode 100644 index 55707fc5..00000000 Binary files a/docs/not-expired-page.png and /dev/null differ diff --git a/docs/page-expiry.md b/docs/page-expiry.md index a2124262..1b9c7296 100644 --- a/docs/page-expiry.md +++ b/docs/page-expiry.md @@ -1,84 +1,3 @@ # Page Expiry and Review Notices -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. - -![](not-expired-page.png) - -If the page needs to be reviewed, we show a red box saying the page might not -be accurate. - -![](expired-page.png) - -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. - -![](last-reviewed-only.png) - -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 -[tech-docs-monitor](https://github.com/alphagov/tech-docs-monitor) to post -messages to Slack when pages have expired. +This content has been moved to .