govuk_tech_docs 6.0.1 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e490b72c74aec01a8e39fa25446e74c7b85cdb81b8e95902d823fc6619ffeabe
-  data.tar.gz: a0a7fee77936966f916c0c6351a5614bdf33e6086ee1a0eeab19dca60deb518b
+  metadata.gz: 9db5229bb2ed62d045e446c4e58b00b534358309485c0bf431a79b290618a69e
+  data.tar.gz: 12fef07d23a5ead0eb3befdb8f32dba7ee9fc2a3176796b6d0db9c9c11367715
 SHA512:
-  metadata.gz: 5df8899a2930b154ed270903e47523eb1c4246c074bab40681872d89ecbff9e0ce6510817547d4a3b1120a68510fe29ae9d6a399835706fd6ab3420c3a20c326
-  data.tar.gz: e7bb22be432a4f76a8fa265d09a62747d5ad4be4fae6d85638f2085e96e10665aa311b708a644e2923eda2afdcc1f31f852d538372083d574a2477d88c2b87dc
+  metadata.gz: 55fbf011e6d71d37e2847e19ead1177b6ab35a01dc7383c53e14e6e0bc1c7506766949dc99f2eb48906008b3b7d48dd545b4019a4ac9dd2b7250769d1bab820e
+  data.tar.gz: 5d263eda7c095456b07eb593d7292efb3a1ec951e6e6b74c19f31f2eb94c3f9d4f79a363b7f5072ac4d1a12741f3f1424f5b441506bfbc8ac769cc8098261e0b

data/CHANGELOG.md

@@ -1,8 +1,18 @@
-## 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.
 
-## 6.0.0
+> Note:
+> openapi3_parser ~> 0.10.1 has a delcares a depndancy on commonmarker >= 1.0
+> 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.beta
 
 - [Bump Design System to V6](https://github.com/alphagov/tech-docs-gem/pull/442), which brings in:
   - changes to the colour palette
@@ -20,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)

data/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/

data/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

data/example/config.rb

@@ -7,3 +7,18 @@ ignore "templates/*"
 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

data/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.

data/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.

data/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 %>

data/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"

data/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)

data/lib/govuk_tech_docs/govuk_nunjuck_componenet_renderer.rb

@@ -0,0 +1,43 @@
+require "schmooze"
+
+module GovukTechDocs
+  class GovukNunjuckComponenetRenderer < Schmooze::Base
+    dependencies nunjucks: "nunjucks"
+
+    def initialize(gem_root)
+      super(gem_root) # Pass it up to Schmooze so it finds node_modules
+      @gem_root = gem_root
+    end
+
+    method :render_nunjucks_template, <<~JS
+      (templateString, templateData, searchPaths) => {
+          const env = nunjucks.configure(searchPaths, { autoescape: true });
+          return env.renderString(templateString, templateData);
+      }
+    JS
+
+    def get_component_template_name(component_name)
+      component_name.to_s.delete_prefix("govuk")
+                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1-\2') # Handle acronyms like "JSONData"
+                  .gsub(/([a-z\d])([A-Z])/, '\1-\2')     # Handle standard "CamelCase"
+                  .downcase
+    end
+
+    def render_govuk_component(component_name, template_data)
+      # 1. Logic for search paths belongs here now
+
+      search_paths = [File.join(@gem_root, "node_modules/govuk-frontend/dist")]
+      component_template_name = get_component_template_name(component_name)
+      # 2. Call the JS method defined above
+      nunjucks_template_string = <<~NJK
+              {% from "govuk/components/#{component_template_name}/macro.njk" import #{component_name} %}
+              {{ #{component_name}(template_data) }}
+      NJK
+      render_nunjucks_template(nunjucks_template_string, { "template_data" => template_data }, search_paths)
+    # rubocop:disable Lint/UselessAssignment
+    rescue StandardError => e
+      raise "Could not load GOV.UK component #{component_name} with data #{template_data}."
+    end
+    # rubocop:enable Lint/UselessAssignment
+  end
+end

data/lib/govuk_tech_docs/version.rb

@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "6.0.1".freeze
+  VERSION = "6.1.0".freeze
 end

data/lib/govuk_tech_docs.rb

@@ -24,6 +24,8 @@ require "govuk_tech_docs/unique_identifier_extension"
 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 @@ module GovukTechDocs
       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 @@ module GovukTechDocs
     else
       context.ignore "search/*"
     end
+
+    if context.config[:tech_docs][:enable_govuk_components]
+      context.activate :custom_method_missing_handler
+    end
   end
 end

data/package-lock.json

@@ -7,7 +7,8 @@
       "name": "tech-docs-gem",
       "license": "MIT",
       "dependencies": {
-        "govuk-frontend": "^6.0.0"
+        "govuk-frontend": "^6.0.0",
+        "nunjucks": "~3.2.4"
       },
       "devDependencies": {
         "jasmine-browser-runner": "^3.0.0",
@@ -76,6 +77,12 @@
         "node": ">=14"
       }
     },
+    "node_modules/a-sync-waterfall": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/a-sync-waterfall/-/a-sync-waterfall-1.0.1.tgz",
+      "integrity": "sha512-RYTOHHdWipFUliRFMCS4X2Yn2X8M87V/OpSqWzKKOGhzqyUxzyVmhHDH9sAvG+ZuQf/TAOFsLCpMw09I1ufUnA==",
+      "license": "MIT"
+    },
     "node_modules/accepts": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
@@ -257,6 +264,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/asap": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz",
+      "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==",
+      "license": "MIT"
+    },
     "node_modules/astral-regex": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/astral-regex/-/astral-regex-1.0.0.tgz",
@@ -474,6 +487,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/commander": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-5.1.0.tgz",
+      "integrity": "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/concat-map": {
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
@@ -3327,6 +3349,31 @@
         "semver": "bin/semver"
       }
     },
+    "node_modules/nunjucks": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/nunjucks/-/nunjucks-3.2.4.tgz",
+      "integrity": "sha512-26XRV6BhkgK0VOxfbU5cQI+ICFUtMLixv1noZn1tGU38kQH5A5nmmbk/O45xdyBhD1esk47nKrY0mvQpZIhRjQ==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "a-sync-waterfall": "^1.0.0",
+        "asap": "^2.0.3",
+        "commander": "^5.1.0"
+      },
+      "bin": {
+        "nunjucks-precompile": "bin/precompile"
+      },
+      "engines": {
+        "node": ">= 6.9.0"
+      },
+      "peerDependencies": {
+        "chokidar": "^3.3.0"
+      },
+      "peerDependenciesMeta": {
+        "chokidar": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/object-assign": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",

data/package.json

@@ -8,7 +8,8 @@
     "test-server": "jasmine-browser-runner serve --config=spec/javascripts/support/jasmine-browser.mjs"
   },
   "dependencies": {
-    "govuk-frontend": "^6.0.0"
+    "govuk-frontend": "^6.0.0",
+    "nunjucks": "~3.2.4"
   },
   "devDependencies": {
     "jasmine-browser-runner": "^3.0.0",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: govuk_tech_docs
 version: !ruby/object:Gem::Version
-  version: 6.0.1
+  version: 6.1.0
 platform: ruby
 authors:
 - Government Digital Service
@@ -276,33 +276,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.78.0
 - !ruby/object:Gem::Dependency
-  name: terser
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: schmooze
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.3
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.3
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
-  name: benchmark
+  name: terser
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: 1.2.3
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.2.3
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -419,6 +433,8 @@ files:
 - example/Gemfile
 - example/config.rb
 - example/config/tech-docs.yml
+- example/source/active-pages/index.html.md.erb
+- example/source/active-pages/sub-section/index.html.md.erb
 - example/source/api-path.html.md
 - example/source/api-reference.html.md
 - example/source/child-of-expired-page.html.md
@@ -488,6 +504,8 @@ files:
 - lib/govuk_tech_docs/api_reference/templates/responses.html.erb
 - lib/govuk_tech_docs/api_reference/templates/schema.html.erb
 - lib/govuk_tech_docs/contribution_banner.rb
+- lib/govuk_tech_docs/custom_method_missing_handler.rb
+- lib/govuk_tech_docs/govuk_nunjuck_componenet_renderer.rb
 - lib/govuk_tech_docs/meta_tags.rb
 - lib/govuk_tech_docs/page_review.rb
 - lib/govuk_tech_docs/pages.rb