diff --git a/Gemfile b/Gemfile index 07e93f1..dc5c858 100644 --- a/Gemfile +++ b/Gemfile @@ -11,3 +11,6 @@ gem 'govuk_tech_docs' gem 'therubyracer' gem 'middleman-gh-pages' + +# Include linter to check for dead internal links +gem 'html-proofer' diff --git a/Gemfile.lock b/Gemfile.lock index 97e1939..010102b 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -39,6 +39,8 @@ GEM eventmachine (>= 0.12.9) http_parser.rb (~> 0.6.0) erubis (2.7.0) + ethon (0.12.0) + ffi (>= 1.3.0) eventmachine (1.2.7) execjs (2.7.0) fast_blank (1.0.0) @@ -66,6 +68,14 @@ GEM hamster (3.0.0) concurrent-ruby (~> 1.0) hashie (3.6.0) + html-proofer (3.13.0) + addressable (~> 2.3) + mercenary (~> 0.3) + nokogiri (~> 1.10) + parallel (~> 1.3) + rainbow (~> 3.0) + typhoeus (~> 1.3) + yell (~> 2.0) http_parser.rb (0.6.0) i18n (0.9.5) concurrent-ruby (~> 1.0) @@ -75,6 +85,7 @@ GEM rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) memoist (0.16.0) + mercenary (0.3.6) method_source (0.9.2) middleman (4.3.5) coffee-script (~> 2.2) @@ -130,9 +141,9 @@ GEM middleman-core (>= 3.2) rouge (~> 2.0) mini_portile2 (2.4.0) - minitest (5.12.2) + minitest (5.13.0) multi_json (1.14.1) - nokogiri (1.10.4) + nokogiri (1.10.5) mini_portile2 (~> 2.4.0) openapi3_parser (0.5.2) commonmarker (~> 0.17) @@ -150,6 +161,7 @@ GEM rack (2.0.7) rack-livereload (0.3.17) rack + rainbow (3.0.0) rake (13.0.0) rb-fsevent (0.10.3) rb-inotify (0.10.0) @@ -173,16 +185,20 @@ GEM thor (0.20.3) thread_safe (0.3.6) tilt (2.0.10) + typhoeus (1.3.1) + ethon (>= 0.9.0) tzinfo (1.2.5) thread_safe (~> 0.1) uglifier (3.2.0) execjs (>= 0.3.0, < 3) + yell (2.2.0) PLATFORMS ruby DEPENDENCIES govuk_tech_docs + html-proofer middleman-gh-pages therubyracer tzinfo-data diff --git a/config.rb b/config.rb index ebdbabd..cc2fb42 100644 --- a/config.rb +++ b/config.rb @@ -1,18 +1,18 @@ require 'govuk_tech_docs' -GovukTechDocs.configure(self, livereload: { js_host: "localhost" }) - -DOCS_LOCATION_IN_GEM = Bundler.rubygems.find_name('govuk_tech_docs').first.full_gem_path + "/docs" - -files.watch :source, path: DOCS_LOCATION_IN_GEM +# Check for broken links +require 'html-proofer' -helpers do - def gem_docs(filename) - raw_markdown = File.read(DOCS_LOCATION_IN_GEM + "/#{filename}") - - # Strip the h1 header from the original markdown file - markdown = raw_markdown.lines[1..-1].join +GovukTechDocs.configure(self, livereload: { js_host: "localhost" }) - markdown +after_build do |builder| + begin + HTMLProofer.check_directory(config[:build_dir], + { :assume_extension => true, + :disable_external => true, + :allow_hash_href => true, + :url_swap => { config[:tech_docs][:host] => "" } }).run + rescue RuntimeError => e + abort e.to_s end end diff --git a/source/amend_project/configuration/index.html.md.erb b/source/amend_project/configuration/index.html.md.erb index 2a1f63b..9549f8f 100644 --- a/source/amend_project/configuration/index.html.md.erb +++ b/source/amend_project/configuration/index.html.md.erb @@ -7,4 +7,227 @@ review_in: 1 day # Configuration options -<%= gem_docs 'configuration.md' %> +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](/amend_project/configuration/#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](/frontmatter.html#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](/amend_project/configuration/#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](/amend_project/configuration/#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. + +## `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]: /review_project/page-expiry/#page-expiry-and-review diff --git a/source/create_project/multipage/index.html.md.erb b/source/create_project/multipage/index.html.md.erb index 5ea4e13..07405f8 100644 --- a/source/create_project/multipage/index.html.md.erb +++ b/source/create_project/multipage/index.html.md.erb @@ -11,7 +11,7 @@ You can create a technical documentation site that splits its content across mul This is suitable for documentation sites that have too much content for the single page format. -You should use the [search feature](/search.html#enable-search) with multipage documentation sites. +You should use the [search feature](/create_project/create_new_project/#enable-search) with multipage documentation sites. ## Basic multipage @@ -30,15 +30,11 @@ multipage_nav: true A typical single page documentation repo has this folder structure: -

-![](/diagrams/Single_page.svg) -

+![](/images/Single_page.svg) A basic multipage documentation repo can have this structure: -

-![](/diagrams/Basic_multipage.svg) -

+![](/images/Basic_multipage.svg) You must amend the documentation repo folder structure to reflect this structure. @@ -118,15 +114,11 @@ multipage_nav: true A typical single page documentation repo has this folder structure: -

-![](/diagrams/Single_page.svg) -

+![](/images/Single_page.svg) A nested multipage documentation repo can have this structure: -

-![](/diagrams/Nested_multipage.svg) -

+![](/images/Nested_multipage.svg) You must amend the documentation repo folder structure to reflect this structure. diff --git a/source/create_project/single_page/index.html.md.erb b/source/create_project/single_page/index.html.md.erb index 77b3f45..606a137 100644 --- a/source/create_project/single_page/index.html.md.erb +++ b/source/create_project/single_page/index.html.md.erb @@ -13,9 +13,9 @@ This is suitable for documentation sites that have do not have a lot of content, ## Organise content files -1. [Create the content files](/create_new_project.html#create-a-new-project) for your documentation site. +1. [Create the content files](/create_project/create_new_project/#create-a-new-documentation-project) for your documentation site. -1. [Amend your content files](/content.html#content-examples) to ready them for your documentation site. +1. [Amend your content files](/amend_project/content/#change-your-content) to ready them for your documentation site. 1. Save your content files inside your documentation repo in your desired hierarchy. @@ -27,7 +27,7 @@ This is suitable for documentation sites that have do not have a lot of content, 1. Amend the `index.html.md.erb` file. - You can either [add a `partial` line](/single_page.html#add-partial-lines) that references each content file that makes up your overall documentation site, or add the content into the `index.html.md.erb` file directly. + You can either [add a `partial` line](/create_project/single_page/#add-partial-lines) that references each content file that makes up your overall documentation site, or add the content into the `index.html.md.erb` file directly. The .html.md.erb files must not have the same name as the folders that the .html.md.erb files use partials refer to. diff --git a/source/diagrams/index.md b/source/diagrams/index.md deleted file mode 100644 index 3c006c6..0000000 --- a/source/diagrams/index.md +++ /dev/null @@ -1 +0,0 @@ -This folder is for diagrams. diff --git a/source/frontmatter.html.md.erb b/source/frontmatter.html.md.erb index 90b62b9..1c874b8 100644 --- a/source/frontmatter.html.md.erb +++ b/source/frontmatter.html.md.erb @@ -4,4 +4,157 @@ title: "Frontmatter" # Frontmatter -<%= gem_docs 'frontmatter.md' %> +"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]: /review_project/page-expiry/#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. + +![](/images/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. +``` + +![](/images/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. +``` + +![](/images/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 diff --git a/source/diagrams/Basic multipage.svg b/source/images/Basic multipage.svg similarity index 100% rename from source/diagrams/Basic multipage.svg rename to source/images/Basic multipage.svg diff --git a/source/diagrams/Basic_multipage.svg b/source/images/Basic_multipage.svg similarity index 100% rename from source/diagrams/Basic_multipage.svg rename to source/images/Basic_multipage.svg diff --git a/source/diagrams/Nested multipage.svg b/source/images/Nested multipage.svg similarity index 100% rename from source/diagrams/Nested multipage.svg rename to source/images/Nested multipage.svg diff --git a/source/diagrams/Nested_multipage.svg b/source/images/Nested_multipage.svg similarity index 100% rename from source/diagrams/Nested_multipage.svg rename to source/images/Nested_multipage.svg diff --git a/source/diagrams/Single_page.svg b/source/images/Single_page.svg similarity index 100% rename from source/diagrams/Single_page.svg rename to source/images/Single_page.svg diff --git a/source/images/core-layout-without-sidebar.png b/source/images/core-layout-without-sidebar.png new file mode 100644 index 0000000..92c94d2 Binary files /dev/null and b/source/images/core-layout-without-sidebar.png differ diff --git a/source/images/core-layout.png b/source/images/core-layout.png new file mode 100644 index 0000000..3725f72 Binary files /dev/null and b/source/images/core-layout.png differ diff --git a/source/images/expired-page.png b/source/images/expired-page.png new file mode 100644 index 0000000..9574398 Binary files /dev/null and b/source/images/expired-page.png differ diff --git a/source/images/last-reviewed-only.png b/source/images/last-reviewed-only.png new file mode 100644 index 0000000..a31a0f5 Binary files /dev/null and b/source/images/last-reviewed-only.png differ diff --git a/source/images/last-reviewed-only.svg b/source/images/last-reviewed-only.svg new file mode 100644 index 0000000..e950b27 --- /dev/null +++ b/source/images/last-reviewed-only.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/images/layout-layout.png b/source/images/layout-layout.png new file mode 100644 index 0000000..13ccd8e Binary files /dev/null and b/source/images/layout-layout.png differ diff --git a/source/images/not-expired-page.png b/source/images/not-expired-page.png new file mode 100644 index 0000000..55707fc Binary files /dev/null and b/source/images/not-expired-page.png differ diff --git a/source/publish_project/push_repo/index.html.md.erb b/source/publish_project/push_repo/index.html.md.erb index 153b244..6134026 100644 --- a/source/publish_project/push_repo/index.html.md.erb +++ b/source/publish_project/push_repo/index.html.md.erb @@ -28,7 +28,7 @@ To push your documentation changes to GitHub for the first time, you must: - MIT license - yes to dependabot -1. [Create a new local documentation repo](/create_new_project.html#create-a-new-project) if required. +1. [Create a new local documentation repo](/create_project/create_new_project/#create-a-new-documentation-project) if required. ## Commit all changes in the local repo diff --git a/source/review_project/page-expiry/index.html.md.erb b/source/review_project/page-expiry/index.html.md.erb index 77ded69..4218a05 100644 --- a/source/review_project/page-expiry/index.html.md.erb +++ b/source/review_project/page-expiry/index.html.md.erb @@ -7,4 +7,85 @@ review_in: 1 day # Page expiry and review -<%= gem_docs 'page-expiry.md' %> +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. + +![](/images/not-expired-page.png) + +If the page needs to be reviewed, we show a red box saying the page might not +be accurate. + +![](/images/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. + +![](/images/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.