Merge pull request #14 from alphagov/documentation

Improve documentation

README.md

@@ -42,6 +42,6 @@ Or, on the command line, run `bundle exec rake jasmine:ci`.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE.md).
+The gem is available as open source under the terms of the [MIT License](LICENSE).
 
 [jas]: https://jasmine.github.io/

docs/configuration.md

@@ -4,61 +4,63 @@ You can configure the site using `config/tech-docs.yml`. [See the PaaS tech docs
 
 These are all the available options:
 
-## `host`
-
-Host to use for canonical URL generation (without trailing slash).
+## `ga_tracking_id`
 
-Example:
+Tracking ID from Google Analytics
 
 ```yaml
-host: https://docs.cloud.service.gov.uk
+ga_tracking_id: UA-XXXX-Y
 ```
 
-## `show_govuk_logo`
+## `github_repo`
 
-Whether to show the GOV.UK crown logo.
+Your repository. Required if [show_contribution_banner](#show-contribution-banner) is true.
 
-default: `true`
+```yaml
+github_repo: alphagov/example-repo
+```
+
+## `google_site_verification`
+
+Adds a [Google Site Verification code](https://support.google.com/webmasters/answer/35179?hl=en) to the meta tags.
 
 ```yaml
-show_govuk_logo: true
+google_site_verification: TvDTuyvdstyusadrCSDrctyd
 ```
 
-## `service_name`
+## `header_links`
 
-The service name in the header.
+Right hand side navigation.
 
 Example:
 
 ```yaml
-service_name: "Platform as a Service"
+header_links:
+  Documentation: /
 ```
 
-## `service_link`
+## `host`
 
-What the service name in the header links to.
+Host to use for canonical URL generation (without trailing slash).
 
-default: '/'
+Example:
 
 ```yaml
-service_link: "/"
+host: https://docs.cloud.service.gov.uk
 ```
 
-## `phase`
+## `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
-phase: "Beta"
+max_toc_heading_level: 6
 ```
 
-## `header_links`
-
-Right hand side navigation.
-
-Example:
+## `phase`
 
 ```yaml
-header_links:
-  Documentation: /
+phase: "Beta"
 ```
 
 ## `prevent_indexing`
@@ -69,34 +71,41 @@ Prevent robots from indexing (e.g. whilst in development)
 prevent_indexing: false
 ```
 
-## `ga_tracking_id`
+## `redirects`
 
-Tracking ID from Google Analytics
+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
-ga_tracking_id: UA-XXXX-Y
+redirects:
+  /old-page.html: https://example.org/something-else.html
+  /another/old-page.html: /another/new-page.html
 ```
 
-## `max_toc_heading_level`
+## `service_name`
 
-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.
+The service name in the header.
+
+Example:
 
 ```yaml
-max_toc_heading_level: 6
+service_name: "Platform as a Service"
 ```
 
-## `google_site_verification`
+## `service_link`
 
-Adds a [Google Site Verification code](https://support.google.com/webmasters/answer/35179?hl=en) to the meta tags.
+What the service name in the header links to.
+
+default: '/'
 
 ```yaml
-google_site_verification: TvDTuyvdstyusadrCSDrctyd
+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` is
+can easily contribute back to the documentation. If turned on [github_repo](#github-repo) is
 required.
 
 Off by default.
@@ -106,21 +115,12 @@ show_contribution_banner: true
 github_repo: alphagov/example-repo
 ```
 
-## `github_repo`
-
-Your repository. Required if `show_contribution_banner` is true.
-
-```yaml
-github_repo: alphagov/example-repo
-```
+## `show_govuk_logo`
 
-## `redirects`
+Whether to show the GOV.UK crown logo.
 
-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.
+default: `true`
 
 ```yaml
-redirects:
-  /old-page.html: https://example.org/something-else.html
-  /another/old-page.html: /another/new-page.html
+show_govuk_logo: true
 ```

docs/frontmatter.md

@@ -1,5 +1,82 @@
 # 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.
+
+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)
+
+Example:
+
+```yaml
+---
+last_reviewed_on: 2018-01-18
+review_in: 6 weeks
+---
+```
+
+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)
+
 ## `old_paths`
 
 Any paths of pages that should redirect to this page.
@@ -12,3 +89,25 @@ 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"
+---
+```
+
+## `title`
+
+The browser title of the page.
+
+```yaml
+---
+title: My beautiful page
+---
+```
+
+[mm]: https://middlemanapp.com/basics/frontmatter

example/source/core-layout.html.md.erb

@@ -0,0 +1,12 @@
+---
+layout: core
+---
+
+<% content_for :sidebar do %>
+  You can put anything in the sidebar.
+<% end %>
+
+
+# Hello!
+
+This page has a configurable sidebar that is independent of the content.

example/source/headings.html.md

@@ -0,0 +1,11 @@
+---
+layout: layout
+---
+
+# The title
+
+## A subheader
+
+### A h3 subheader
+
+## Another subheader