Merge pull request #384 from alphagov/v4-v5-co-hosting

Host v4 in its own folder

.gitignore

@@ -25,3 +25,4 @@ Staticfile.auth
 
 # Sassdocs generated files
 data/sassdoc.json
+data/sassdoc-v4.json

config.rb

@@ -1,5 +1,7 @@
 require "govuk_tech_docs"
+require "lib/header_menu_fix_extension"
 require "lib/sassdocs_helpers"
+require "lib/table_of_contents_helpers"
 
 # Patch the GovukTechDocs cleanly
 # https://www.justinweiss.com/articles/3-ways-to-monkey-patch-without-making-a-mess/
@@ -10,6 +12,9 @@
 
 GovukTechDocs.configure(self)
 
+::Middleman::Extensions.register(:header_menu_fix, HeaderMenuFixExtension)
+activate :header_menu_fix
+
 # Load our own version of GOV.UK Frontend before the one registered by the
 # tech_docs_gem otherwise we may be using styles and scripts
 # from an outdated version the time for the tech_docs_gem to catch up
@@ -20,7 +25,12 @@
 
 helpers do
   include SassdocsHelpers
+  include TableOfContentsHelpers
+
   def markdown(content = nil)
     concat Tilt["markdown"].new(context: @app) { content }.render
   end
 end
+
+page "v4/*", layout: :v4, data: { parent: "/v4/" }
+page "*", data: { parent: "/" }

config/tech-docs.yml

@@ -36,3 +36,7 @@ max_toc_heading_level: 2
 
 show_contribution_banner: true
 github_repo: alphagov/govuk-frontend-docs
+
+header_links:
+  v5.x (Latest): /
+  v4.x: /v4/

lib/header_menu_fix_extension.rb

@@ -0,0 +1,29 @@
+##
+# Middleman extension fixing the menu button in the header
+#
+# The element is missing a `hidden` attribute, which the extension
+# adds using Nokogiri when rendering the `layouts/_header.erb` partial
+#
+# @see https://middlemanapp.com/advanced/custom-extensions/
+class HeaderMenuFixExtension < Middleman::Extension
+  def initialize(app, options_hash = {}, &block)
+    super
+
+    # @see https://github.com/middleman/middleman/blob/ad0e0ee9ba5e017e4f3f1cc861f4fa2a4c04f198/middleman-core/lib/middleman-core/extension.rb#L63
+    app.after_render do |content, path|
+      # The `after_render` hook will trigger for each renderer (eg. md, erb)
+      # and each partial/layout being rendered. We only care about the one
+      # containing the menu button, which is `layouts/_header.erb`
+      next unless path == "layouts/_header.erb"
+
+      html = Nokogiri::HTML5.fragment(content)
+
+      menu_button = html.search(".govuk-header__menu-button").first
+      next unless menu_button
+
+      menu_button["hidden"] = ""
+
+      html.serialize
+    end
+  end
+end

lib/sassdocs_helpers.rb

@@ -4,10 +4,10 @@ module SassdocsHelpers
   ORDER = %w[settings tools helpers].freeze
 
   def format_sassdoc_data(data)
-    raise "No data in data/sassdocs.json, run `npm install` to generate." unless data.respond_to?(:sassdoc)
+    raise "No data in data/sassdocs.json, run `npm install` to generate." if data.nil?
 
     # Remove private API entries
-    public_entries = data.sassdoc.select { |item| item.access == "public" }
+    public_entries = data.select { |item| item.access == "public" }
     # Remove vendored files, for example SassMQ
     public_entries = public_entries.reject { |item| item.file.path.start_with?("vendor") }
     # Group the items by their 'group', for example 'Settings' or 'Helpers'

lib/table_of_contents_helpers.rb

@@ -0,0 +1,55 @@
+##
+# Extra helpers for customising the rendering of the table of contents in the sidebar
+# so it accomodates a separate table of contents for the `v4` section of the site
+module TableOfContentsHelpers
+  ##
+  # Override `render_page_tree` so it can be bypassed when rendering the children
+  # of a specific given page (stored in `@parent_page`) (see `without_child_pages_for` bellow).
+  # This enables not rendering the child pages of the `index`, as they'll be rendered
+  # individually as well.
+  # This is due to the lack of abstraction for the test checking whether to render a resource
+  # as a single item or an item the tree of its children
+  # See: https://github.com/alphagov/tech-docs-gem/blob/207bcb8593197f3aad8983018ca0a91db7783410/lib/govuk_tech_docs/table_of_contents/helpers.rb#L74
+  def render_page_tree(resources, *args)
+    return "" if resources == @parent_page&.children
+
+    super(resources, *args)
+  end
+
+  ##
+  # Temporarily excludes the children of the given page
+  # from being rendered by `render_page_tree` while it runs
+  # in the block passed to this method
+  #
+  # @example
+  #
+  #  without_child_pages_for(a_page) do
+  #    render_page_tree(some_pages_including_a_page,...)
+  #  end
+  def without_child_pages_for(parent_page)
+    @parent_page = parent_page
+
+    yield
+  ensure
+    @parent_page = nil
+  end
+
+  ##
+  # Forces a page configured hidden from the navigation with
+  # `hide_in_navigation: true` to be rendered in the navigation when
+  # `render_page_tree` runs in the block this method receives
+  #
+  # @example
+  #
+  #  with_page_in_navigation(a_page) do
+  #    render_page_tree(some_pages_including_a_page,...)
+  #  end
+  def with_page_in_navigation(page)
+    original = page.data.hide_in_navigation
+    page.data.hide_in_navigation = false
+
+    yield
+  ensure
+    page.data.hide_in_navigation = original
+  end
+end

package.json

@@ -3,13 +3,15 @@
   "name": "govuk-frontend-docs",
   "version": "1.0.0",
   "scripts": {
-    "postinstall": "npm run build:sassdoc",
+    "postinstall": "npm run build:sassdoc && npm run build:sassdocv4",
     "build:sassdoc": "sassdoc --parse node_modules/govuk-frontend/dist/govuk/ > data/sassdoc.json",
+    "build:sassdocv4": "sassdoc --parse node_modules/govuk-frontend-v4/govuk/ > data/sassdoc-v4.json",
     "lint": "standard",
     "check-links": "hyperlink --canonicalroot https://frontend.design-system.service.gov.uk --internal --recursive deploy/public/index.html --skip 'property=\"og:image\"' | tee check-links.log | tap-mocha-reporter min"
   },
   "devDependencies": {
     "govuk-frontend": "^5.0.0-beta.1",
+    "govuk-frontend-v4": "npm:govuk-frontend@^4.7.0",
     "hyperlink": "^5.0.4",
     "sassdoc": "^2.7.4",
     "standard": "^17.1.0",

source/configure-components-with-javascript/index.html.md.erb

@@ -5,7 +5,7 @@ weight: 76
 
 # Configure components with JavaScript
 
-You can configure some of the components in GOV.UK Frontend to customise their behaviour or to [localise their JavaScript to use a language other than English](/localise-govuk-frontend/).
+You can configure some of the components in GOV.UK Frontend to customise their behaviour or to [localise their JavaScript to use a language other than English](../localise-govuk-frontend/).
 
 You can configure a component by:
 
@@ -24,7 +24,7 @@ You can find the Nunjucks macro options by selecting the Nunjucks tab in the exa
 
 If you're using HTML, you can pass configuration by adding data attributes to the component's outermost element (the element that has the `data-module` attribute). This is how our Nunjucks macros forward the configuration to the JavaScript components in the browser. Data attributes use kebab-case.
 
-Some configuration options are grouped under a namespace to keep related options together. For example, [the localisation options](/localise-govuk-frontend/) are grouped under the `i18n` namespace. When using these options, include the namespace as a prefix followed by a period as part of the attribute name.
+Some configuration options are grouped under a namespace to keep related options together. For example, [the localisation options](../localise-govuk-frontend/) are grouped under the `i18n` namespace. When using these options, include the namespace as a prefix followed by a period as part of the attribute name.
 
 For options accepting object values, you'll need to set one attribute for each key of that object. Suffix the attribute name (including any namespace) with a period and the name of the key in the object.
 
@@ -48,7 +48,7 @@ If your configuration contains [quotes or other reserved HTML characters](https:
 
 Configuration is read from data attributes when the component is initialised. Changes to the data attributes made after the component has been initialised will have no effect on the behaviour of the component.
 
-Read the [JavaScript API Reference](/javascript-api-reference/) for the configuration accepted by each component. You'll need to convert the configuration names into kebab-case.
+Read the [JavaScript API Reference](../javascript-api-reference/) for the configuration accepted by each component. You'll need to convert the configuration names into kebab-case.
 
 ## Passing configuration to a new instance of a component in JavaScript
 
@@ -63,7 +63,7 @@ The object should include key-value pairs. The keys should be written in camelCa
 
 Components will merge the configuration provided at initialisation with those provided as data-attributes. If the same option is defined in both, the one provided by data-attributes will take precedence.
 
-Some configuration options might accept object values or be grouped under a namespace to keep related things together. For example, [the localisation options](/localise-govuk-frontend/) are grouped under the `i18n` namespace. When using these options, use nested objects. For example:
+Some configuration options might accept object values or be grouped under a namespace to keep related things together. For example, [the localisation options](../localise-govuk-frontend/) are grouped under the `i18n` namespace. When using these options, use nested objects. For example:
 
 ```javascript
 new CharacterCount($element, {
@@ -83,7 +83,7 @@ new CharacterCount($element, {
 })
 ```
 
-Read the [JavaScript API Reference](/javascript-api-reference/) to see what configuration each component accepts.
+Read the [JavaScript API Reference](../javascript-api-reference/) to see what configuration each component accepts.
 
 ## Passing configuration using the initAll function
 

source/get-started/index.html.md.erb

@@ -17,9 +17,9 @@ You will need to do all the following steps to get your component working.
 
 ## 1. Install
 
-[Install GOV.UK Frontend using npm](/installing-with-npm/).
+[Install GOV.UK Frontend using npm](../installing-with-npm/).
 
-If you've installed using precompiled files, get started with [a basic page](/install-using-precompiled-files/#check-an-example-page) instead.
+If you've installed using precompiled files, get started with [a basic page](../install-using-precompiled-files/#check-an-example-page) instead.
 
 ## 2. Add the HTML for a component to your application
 
@@ -62,7 +62,7 @@ Your component will not use the right font or images until you've added GOV.UK F
 
 2. Run your application, then use [the Fonts tab in Firefox Page Inspector](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts#The_Fonts_tab) to check the accordion is using the GDS Transport font.
 
-In your live application, we recommend [using an automated task or your build pipeline](/importing-css-assets-and-javascript/#font-and-image-assets) instead of copying the files manually.
+In your live application, we recommend [using an automated task or your build pipeline](../importing-css-assets-and-javascript/#font-and-image-assets) instead of copying the files manually.
 
 ## 5. Get the JavaScript working
 
@@ -92,6 +92,6 @@ In your live application, we recommend [using an automated task or your build pi
 In your live application:
 
 - you must use `initAll` to initialise all components that use GOV.UK Frontend's JavaScript, or some components will not work correctly for disabled users who use assistive technologies
-- we recommend [using an automated task or your build pipeline](/importing-css-assets-and-javascript/#javascript) instead of copying the files manually
+- we recommend [using an automated task or your build pipeline](../importing-css-assets-and-javascript/#javascript) instead of copying the files manually
 
 You can now get the full code for page layouts and other components from the [Design System website](https://design-system.service.gov.uk/).

source/install-using-precompiled-files/index.html.md.erb

@@ -16,7 +16,7 @@ You can install GOV.UK Frontend by copying our CSS, JavaScript and asset files i
 
 You’ll not be able to:
 
-- change [Sass settings](/sass-api-reference/), for example override colours or set your own font
+- change [Sass settings](../sass-api-reference/), for example override colours or set your own font
 - use the Nunjucks code from the [Design System website](https://design-system.service.gov.uk/) to add components
 - import an individual component’s CSS or JavaScript
 - use GOV.UK Frontend's colours or mixins in your custom code
@@ -63,4 +63,4 @@ You’ll not be able to:
 
 You can now get the full code for page layouts and other components from the [Design System website](https://design-system.service.gov.uk/).
 
-If the accordion does not work, you can [find out more about how to import GOV.UK Frontend's CSS and JavaScript](/importing-css-assets-and-javascript/#import-css-assets-and-javascript).
+If the accordion does not work, you can [find out more about how to import GOV.UK Frontend's CSS and JavaScript](../importing-css-assets-and-javascript/#import-css-assets-and-javascript).

source/installing-with-npm/index.html.md.erb

@@ -25,7 +25,7 @@ weight: 10
 
     Although GOV.UK Frontend currently supports LibSass (version 3.3.0 and above) and Ruby Sass (version 3.4.0 and above), we will remove support in future. If you're using either of these Sass compilers, you should [migrate to Dart Sass](https://sass-lang.com/blog/libsass-is-deprecated#how-do-i-migrate) as soon as you reasonably can.
 
-You can also [install Nunjucks v3.0.0 or later](https://www.npmjs.com/package/nunjucks) if you want to [use GOV.UK Frontend's Nunjucks macros](/use-nunjucks/).
+You can also [install Nunjucks v3.0.0 or later](https://www.npmjs.com/package/nunjucks) if you want to [use GOV.UK Frontend's Nunjucks macros](../use-nunjucks/).
 
 ## Install GOV.UK Frontend
 
@@ -37,4 +37,4 @@ npm install govuk-frontend --save
 
 When the installation finishes, the `govuk-frontend` package will be in your `node_modules` folder.
 
-You should now get started by [getting the CSS, assets and JavaScript working](/get-started/) with one GOV.UK Frontend component.
+You should now get started by [getting the CSS, assets and JavaScript working](../get-started/) with one GOV.UK Frontend component.

source/javascript-api-reference/index.html.md.erb

@@ -8,7 +8,7 @@ weight: 80
 Some of our components can receive configuration options when you create an
 instance in JavaScript. This page lists the available options for these
 components. You can find further information on how to [configure these options
-in our guidance](/configure-components-with-javascript/).
+in our guidance](../configure-components-with-javascript/).
 
 You can pass these options in an object either as:
 
@@ -179,7 +179,7 @@ Message displayed when the number of characters is under the configured maximum,
 `maxlength`. This message is displayed visually and through assistive
 technologies. The component will replace the `%{count}` placeholder with the
 number of remaining characters. This is a [pluralised list of
-messages](/localise-govuk-frontend/#understanding-pluralisation-rules).
+messages](../localise-govuk-frontend/#understanding-pluralisation-rules).
 
 Default:
 
@@ -212,7 +212,7 @@ Message displayed when the number of characters is over the configured maximum,
 `maxlength`. This message is displayed visually and through assistive
 technologies. The component will replace the `%{count}` placeholder with the
 number of remaining characters. This is a [pluralised list of
-messages](/localise-govuk-frontend/#understanding-pluralisation-rules).
+messages](../localise-govuk-frontend/#understanding-pluralisation-rules).
 
 Default:
 
@@ -231,7 +231,7 @@ Message displayed when the number of words is under the configured maximum,
 `maxwords`. This message is displayed visually and through assistive
 technologies. The component will replace the `%{count}` placeholder with the
 number of remaining words. This is a [pluralised list of
-messages](/localise-govuk-frontend/#understanding-pluralisation-rules).
+messages](../localise-govuk-frontend/#understanding-pluralisation-rules).
 
 Default:
 
@@ -264,7 +264,7 @@ Message displayed when the number of words is over the configured maximum,
 `maxwords`. This message is displayed visually and through assistive
 technologies. The component will replace the `%{count}` placeholder with the
 number of remaining words. This is a [pluralised list of
-messages](/localise-govuk-frontend/#understanding-pluralisation-rules).
+messages](../localise-govuk-frontend/#understanding-pluralisation-rules).
 
 Default:
 

source/layouts/v4.erb

@@ -0,0 +1,26 @@
+<%
+wrap_layout :core do
+  html = yield
+
+  content_for(:toc_module, "in-page-navigation")
+
+  # For v4 pages, we only want the pages under the `v4` folder
+  resources = sitemap.resources.select do |r|
+    r.path.start_with?('v4/')
+  end
+
+  content_for :sidebar do
+    # Because all the pages for `v4` are children of `v4/index.html`,
+    # they'd appear as items under the v4 index in the sidebar, which we don't want
+    # so we exclude the rendering of child pages for the v4 index page
+    v4_index = resources.find{ |r| r.path == 'v4/index.html' }
+
+    with_page_in_navigation(v4_index) do
+      without_child_pages_for(v4_index) do
+        render_page_tree(resources, current_page, config, html)
+      end
+    end
+  end
+
+  html
+end %>

source/localise-govuk-frontend/index.html.md.erb

@@ -37,7 +37,7 @@ If you're using the Nunjucks macro, look at the Nunjucks macro options table in
 
 If you're using the HTML directly, you can customise the text used in the JavaScript by passing configuration using data attributes.
 
-Alternatively, you can [configure the component with JavaScript](/configure-components-with-javascript/) at the point you initialise it or when using `initAll`.
+Alternatively, you can [configure the component with JavaScript](../configure-components-with-javascript/) at the point you initialise it or when using `initAll`.
 
 The naming conventions for:
 
@@ -92,7 +92,7 @@ If you're looking to keep English messages and override only one of the plural f
 
 Our components will replace the `%{count}` placeholder with the number used for picking the plural category.
 
-The following example shows how to provide pluralisation options using the different ways you can [configure components with JavaScript](/configure-components-with-javascript/):
+The following example shows how to provide pluralisation options using the different ways you can [configure components with JavaScript](../configure-components-with-javascript/):
 
 With Nunjucks
 

source/sass-api-reference/index.html.md.erb

@@ -5,7 +5,7 @@ weight: 90
 
 # Sass API reference
 
-<% format_sassdoc_data(data).each do |group_name, subgroups| %>
+<% format_sassdoc_data(data[:sassdoc]).each do |group_name, subgroups| %>
 
 ## <%= group_heading(group_name) %>