Merge pull request #460 from alphagov/release/v6-1-0-beta

Release/v6 1 0 beta

Author: JC-DSIT

CHANGELOG.md

@@ -1,4 +1,9 @@
-## 6.0.1
+# 6.1.0
+
+- [Add custom extensions to render GOV.UK Design System nunjucks components](https://github.com/alphagov/tech-docs-gem/pull/443/changes)
+- [Fix inconsistent active tab behaviour](https://github.com/alphagov/tech-docs-gem/pull/452)
+
+# 6.0.1
 
 - Update version of `openapi3_parser` allowing support for Ruby 4.0.
 
@@ -7,7 +12,7 @@
 > commonmarker >= 1.0 declares required_ruby_version >= 3.3.22
 > If you are using an older ruby verion this may cause issues in your environment. We recommend upgrading to a version >= 3.
 
-## 6.0.0
+## 6.0.0.beta
 
 - [Bump Design System to V6](https://github.com/alphagov/tech-docs-gem/pull/442), which brings in:
   - changes to the colour palette
@@ -25,7 +30,6 @@ ability, we're marking it as a major bump.
 - [Bump jasmine-core from 5.5.0 to 5.13.0 #448](https://github.com/alphagov/tech-docs-gem/pull/448)
 - [Ban pre|post-install NPM scripts #453](https://github.com/alphagov/tech-docs-gem/pull/453)
 
-
 ## 5.2.1
 
 - [Add option to not render child resources when creating a table of contents](https://github.com/alphagov/tech-docs-gem/pull/439/changes)

README.md

@@ -15,6 +15,8 @@ Find out how to [contribute](https://tdt-documentation.london.cloudapps.digital/
 
 This gem uses [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend), part of the [GOV.UK Design System](https://design-system.service.gov.uk/).
 
+This gem can also use [GOV.UK Design System nunjucks components](https://design-system.service.gov.uk/components/).  It is recommended that you use these as they are user researched and accessibility tested.  An example using the `govukButton` component is available in the [example site in this gem](./example/source/index.html.md.erb).
+
 We use `npm` to download the govuk-frontend package. To update to a new version, change the version in the [package.json file](package.json) and run `npm update`.
 
 ## Table of contents helper functions
@@ -158,9 +160,8 @@ The documentation is [© Crown copyright][copyright] and available under the ter
 [mit]: LICENCE
 [copyright]: http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/
 [ogl]: http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
-[tdt-docs]: https://tdt-documentation.london.cloudapps.digital
+[tdt-docs]: https://github.com/alphagov/tdt-documentation/
 [tdt-template]: https://github.com/alphagov/tech-docs-template
-[tdt-readme]: https://github.com/alphagov/tech-docs-template/blob/main/README.md
 [mmt]: https://middlemanapp.com/advanced/project_templates/
 
 [jas]: https://jasmine.github.io/

example/config.rb

@@ -7,3 +7,18 @@
 proxy "/a-proxied-page.html", "templates/proxy_template.html", locals: {
   title: "I am a title",
 }
+
+gem_root = File.expand_path("..", __dir__)
+files.watch :reload, path: File.join(gem_root, "lib")
+
+configure :development do
+  ready do
+    files.on_change :reload do |changed|
+      changed.each do |file|
+        next unless file.full_path.extname == ".rb"
+
+        load file.full_path.to_s
+      end
+    end
+  end
+end

example/config/tech-docs.yml

@@ -1,6 +1,9 @@
 # Host to use for canonical URL generation (without trailing slash)
 host: https://docs.example.com
 
+# Enable GOV.UK Design System nunjucks components (https://design-system.service.gov.uk/components)
+enable_govuk_components: true
+
 # Header-related options
 show_govuk_logo: true
 service_name: My First Service
@@ -14,6 +17,7 @@ header_links:
   Expired with owner: /expired-page-with-owner.html
   Not expired page: /not-expired-page.html
   Single page nav: /single-page-nav.html
+  Active pages: /active-pages/
 
 footer_links:
   Accessibility: /hidden-page.html

example/source/active-pages/index.html.md.erb

@@ -0,0 +1,7 @@
+---
+title: Active page section root
+---
+
+# This is a section landing page, under the "Active pages" navigation link.
+
+The "Active pages" navigation link should be active.

example/source/active-pages/sub-section/index.html.md.erb

@@ -0,0 +1,7 @@
+---
+title: Active page sub section root
+---
+
+# This is a section sub section, under the "Active pages" navigation link.
+
+The "Active pages" navigation link should STILL BE active.

example/source/index.html.md.erb

@@ -18,5 +18,10 @@ To change the title of the page or include additional files you'll need to edit
 If you want slightly more control, you can always use <strong>HTML</strong>.
 
 For more detail and troubleshooting, take a look at the `README.md` file in the root of this project.
+<% if config[:tech_docs][:enable_govuk_components] %>
 
-<%= warning_text "Look out! A warning!" %>
+<%= govukButton({
+  text: "Click me!"
+}) %>
+
+<% end %>

govuk_tech_docs.gemspec

@@ -54,9 +54,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency "openapi3_parser", "~> 0.10.1"
   spec.add_dependency "redcarpet", "~> 3.6"
   spec.add_dependency "sassc-embedded", "~> 1.78.0"
-  spec.add_dependency "terser", "~> 1.2.3"
 
   spec.add_development_dependency "benchmark"
+  spec.add_dependency "schmooze", "~> 0.2.0"
+  spec.add_dependency "terser", "~> 1.2.3"
   spec.add_development_dependency "byebug"
   spec.add_development_dependency "capybara", "~> 3.32"
   spec.add_development_dependency "ostruct"

lib/govuk_tech_docs.rb

@@ -24,6 +24,8 @@
 require "govuk_tech_docs/unique_identifier_generator"
 require "govuk_tech_docs/warning_text_extension"
 require "govuk_tech_docs/api_reference/api_reference_extension"
+require "govuk_tech_docs/custom_method_missing_handler"
+require "govuk_tech_docs/govuk_nunjuck_componenet_renderer"
 
 module SassWarningSupressor
   def warn(message)
@@ -101,11 +103,35 @@ def format_date(date)
       end
 
       def active_page(page_path)
-        [
-          page_path == "/" && current_page.path == "index.html",
-          "/#{current_page.path}" == page_path,
-          !current_page.data.parent.nil? && current_page.data.parent.to_s == page_path,
-        ].any?
+        # if we are on the homepage e.g  Documentation: /
+        if page_path == "/" && current_page.url == "/"
+          return true
+        end
+
+        # if we are on a single page the header links point to e.g Expired page: /expired-page.html
+        if "/#{current_page.path}" == page_path
+          return true
+        end
+
+        # If the doc maintainer has set the parent data in the frontmatter for the current page,
+        # and it matches the value in the config e.g
+        # Expired page: /expired-page.html (config) and parent: /expired-page.html (child-of-expired-page.html)
+        if !current_page.data.parent.nil? && current_page.data.parent.to_s == page_path
+          return true
+        end
+
+        # If we have a nested directory structure that matches a navigation link e.g  Active pages: /active-pages/
+        if current_page.url.start_with?(page_path)
+          # feels like a weird check, but stops false positive where "/" for root is also the start of "/active-pages"
+          if page_path == "/"
+            return current_page.url == "/"
+          end
+
+          # safe to return true, since we aren't in the situation above
+          return true
+        end
+        # no other reason to believe we're active
+        false
       end
     end
 
@@ -138,5 +164,9 @@ def active_page(page_path)
     else
       context.ignore "search/*"
     end
+
+    if context.config[:tech_docs][:enable_govuk_components]
+      context.activate :custom_method_missing_handler
+    end
   end
 end

lib/govuk_tech_docs/custom_method_missing_handler.rb

@@ -0,0 +1,30 @@
+require "middleman-core"
+
+module GovukTechDocs
+  class CustomMethodMissingHandler < Middleman::Extension
+    def initialize(app, options_hash = {}, &block)
+      super
+    end
+
+    helpers do
+      def method_missing(method_name, *args, &block)
+        if method_name.to_s.start_with?("govuk")
+          begin
+            data = args.first || {}
+            @renderer ||= GovukTechDocs::GovukNunjuckComponenetRenderer.new(File.expand_path("../../", __dir__))
+            @renderer.render_govuk_component(method_name, data).html_safe
+          rescue StandardError => e
+            raise e
+          end
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        method_name.to_s.start_with?("govuk") || super
+      end
+    end
+  end
+end
+::Middleman::Extensions.register(:custom_method_missing_handler, GovukTechDocs::CustomMethodMissingHandler)