Merge pull request #108 from alphagov/fix-all-broken-links-forever

Fix all broken links and add link checker

Author: bravegrape

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'

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

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

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

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:
 
-<br/><br/>
-![](/diagrams/Single_page.svg)
-<br/><br/>
+![](/images/Single_page.svg)
 
 A basic multipage documentation repo can have this structure:
 
-<br/><br/>
-![](/diagrams/Basic_multipage.svg)
-<br/><br/>
+![](/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:
 
-<br/><br/>
-![](/diagrams/Single_page.svg)
-<br/><br/>
+![](/images/Single_page.svg)
 
 A nested multipage documentation repo can have this structure:
 
-<br/><br/>
-![](/diagrams/Nested_multipage.svg)
-<br/><br/>
+![](/images/Nested_multipage.svg)
 
 You must amend the documentation repo folder structure to reflect this structure.