govuk_tech_docs 3.3.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e56428dbc592284d70ca0c9880c6c99fd10cd72da62a7008bbc11237e49c486c
-  data.tar.gz: b328aa30ba2a6fc8666abf3c9ede2a7a93639604ef0a1705626632479400f117
+  metadata.gz: ac3b9630e3b7c40e2029a0e115dc1054e025f14d35fc07b81b4ab531cee7bea2
+  data.tar.gz: e414f5b7ab807ef05e95ec5f3281d68abd444e712f8355ed4bbac2dcd7c17dfd
 SHA512:
-  metadata.gz: c7aad01df604f63f875ecd96a9ace7f003e7a34eb6eb71c176e36cb1a11a8bf61af50231561338d8853c2c853e8d0aa5d69388f8ef7e5e83cf3355fc3b7cc9aa
-  data.tar.gz: c0f2915a6922e499f4ed1eb39262c7176bc64df8467a0be1ba1579af8cdea0fc6bef3c1415822f1aff6f80c679ed0d9fedce4a4ccd9799932bf0aabb196a4747
+  metadata.gz: c3b71ef93eac71413d405bb1a504b15a2692a498ba397c93f0d4aabb8f231650176e9b6b55edc620128fdec5fc0fa8a60f02d70eacd1092b1c52611966f84685
+  data.tar.gz: 1a6f93c4c7f2079adb79e02e734e7fe7f375d503ad0d20c3be59df2696d0efacbbbd189f6822e2263e9245925407d88fe96f02dbcd5aa6e099d636954c3440e1

data/.github/workflows/publish.yaml

@@ -16,22 +16,24 @@ jobs:
       go: ${{ steps.gem_version.outputs.new_version }}
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3'
 
       - name: Check if new version to release
         id: gem_version
         run: |
           gem_version=$(ruby -r rubygems -e "puts Gem::Specification::load('govuk_tech_docs.gemspec').version")
-          echo "::set-output name=gem_version::$gem_version"
+          echo "gem_version=$gem_version" >> "$GITHUB_OUTPUT"
 
           if git fetch origin "refs/tags/v$gem_version" >/dev/null 2>&1
           then
             echo "Tag 'v$gem_version' already exists"
-            echo "::set-output name=new_version::false"
+            echo "new_version=false" >> "$GITHUB_OUTPUT"
           else
-            echo "::set-output name=new_version::true"
+            echo "new_version=true" >> "$GITHUB_OUTPUT"
           fi
 
   deploy:
@@ -44,15 +46,16 @@ jobs:
     if: ${{ needs.pre.outputs.go == 'true' }}
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
-      - uses: actions/setup-node@v2
+      - uses: actions/setup-node@v3
         with:
+          node-version-file: '.nvmrc'
           cache: 'npm'
-          node-version: '14'
 
       - uses: ruby/setup-ruby@v1
         with:
+          ruby-version: '3'
           bundler-cache: true
 
       - name: Publish

data/.github/workflows/test.yaml

@@ -7,16 +7,21 @@ jobs:
     name: Test
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        ruby: ['2.7', '3.2']
+
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
-      - uses: actions/setup-node@v2
+      - uses: actions/setup-node@v3
         with:
-          node-version: '14'
+          node-version-file: '.nvmrc'
           cache: 'npm'
 
       - uses: ruby/setup-ruby@v1
         with:
+          ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
 
       - name: Run tests

data/.nvmrc

@@ -1 +1 @@
-14
+18

data/.rubocop.yml

@@ -2,6 +2,9 @@ inherit_gem:
   rubocop-govuk:
     - config/default.yml
 
+AllCops:
+  TargetRubyVersion: 2.7
+
 Layout/HeredocIndentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 3.4.0
+
+### New features
+
+- Footer and header links now work with relative links. Thanks to [@eddgrant](https://github.com/eddgrant) for contributing this feature.
+
+  See [pull request #325: Support sites deployed on a path other than "/" when generating header and footer links](https://github.com/alphagov/tech-docs-gem/pull/325) for more details.
+
+### Fixes
+
+- You no longer need to downgrade Haml yourself, `bundle install` will now make sure Haml 6 is not installed (see issue [#318: Error: Filters is not a module](https://github.com/alphagov/tech-docs/gem/issues/318)).
+
 ## 3.3.1
 
 This change solves a potential security issue with HTML snippets. Pages indexed in search results have their entire contents indexed, including any HTML code snippets. These HTML snippets would appear in the search results unsanitised, making it possible to render arbitrary HTML or run arbitrary scripts.

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in govuk_tech_docs.gemspec
 gemspec

data/govuk_tech_docs.gemspec

@@ -1,13 +1,14 @@
-# coding: utf-8
-lib = File.expand_path("../lib", __FILE__)
+require "English"
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "govuk_tech_docs/version"
 
 `npm install`
-abort 'npm install failed' unless $?.success?
+abort "npm install failed" unless $CHILD_STATUS.success?
 
-unless File.exist?('node_modules/govuk-frontend/govuk/all.scss')
-  abort 'govuk-frontend npm package not installed'
+unless File.exist?("node_modules/govuk-frontend/govuk/all.scss")
+  abort "govuk-frontend npm package not installed"
 end
 
 Gem::Specification.new do |spec|
@@ -16,8 +17,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Government Digital Service"]
   spec.email         = ["govuk-dev@digital.cabinet-office.gov.uk"]
 
-  spec.summary       = %q{Gem to distribute the GOV.UK Tech Docs Template}
-  spec.description   = %q{Gem to distribute the GOV.UK Tech Docs Template. See https://github.com/alphagov/tech-docs-gem for the project.}
+  spec.summary       = "Gem to distribute the GOV.UK Tech Docs Template"
+  spec.description   = "Gem to distribute the GOV.UK Tech Docs Template. See https://github.com/alphagov/tech-docs-gem for the project."
   spec.homepage      = "https://github.com/alphagov/tech-docs-gem"
   spec.license       = "MIT"
 
@@ -30,10 +31,13 @@ Gem::Specification.new do |spec|
 
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = %w[lib]
+
+  spec.required_ruby_version = ">= 2.7.0"
 
   spec.add_dependency "autoprefixer-rails", "~> 10.2"
   spec.add_dependency "chronic", "~> 0.10.2"
+  spec.add_dependency "haml", "< 6.0.0"
   spec.add_dependency "middleman", "~> 4.0"
   spec.add_dependency "middleman-autoprefixer", "~> 2.10.0"
   spec.add_dependency "middleman-compass", ">= 4.0.0"
@@ -50,5 +54,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "jasmine", "~> 3.5.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.9.0"
-  spec.add_development_dependency "rubocop-govuk", "~> 3.5.0"
+  spec.add_development_dependency "rubocop-govuk", "~> 4.10.0"
 end

data/lib/govuk_tech_docs/api_reference/api_reference_extension.rb

@@ -37,7 +37,7 @@ module GovukTechDocs
 
       def uri?(string)
         uri = URI.parse(string)
-        %w(http https).include?(uri.scheme)
+        %w[http https].include?(uri.scheme)
       rescue URI::BadURIError
         false
       rescue URI::InvalidURIError

data/lib/govuk_tech_docs/api_reference/api_reference_renderer.rb

@@ -124,15 +124,15 @@ module GovukTechDocs
           properties.merge!(all_of_schema.properties.to_h)
         end
 
-        properties.each_with_object({}) do |(name, schema), memo|
-          memo[name] = case schema.type
-                       when "object"
-                         schema_properties(schema.items || schema)
-                       when "array"
-                         schema.items ? [schema_properties(schema.items)] : []
-                       else
-                         schema.example || schema.type
-                       end
+        properties.transform_values do |schema|
+          case schema.type
+          when "object"
+            schema_properties(schema.items || schema)
+          when "array"
+            schema.items ? [schema_properties(schema.items)] : []
+          else
+            schema.example || schema.type
+          end
         end
       end
 
@@ -144,7 +144,7 @@ module GovukTechDocs
       end
 
       def get_renderer(file)
-        template_path = File.join(File.dirname(__FILE__), "templates/" + file)
+        template_path = File.join(File.dirname(__FILE__), "templates/#{file}")
         template = File.open(template_path, "r").read
         ERB.new(template)
       end

data/lib/govuk_tech_docs/path_helpers.rb

@@ -1,18 +1,29 @@
+require "uri"
 module GovukTechDocs
   module PathHelpers
-    def get_path_to_resource(config, resource, current_page)
-      if config[:relative_links]
-        resource_path_segments = resource.path.split("/").reject(&:empty?)[0..-2]
-        resource_file_name = resource.path.split("/")[-1]
+    # Some useful notes from https://www.rubydoc.info/github/middleman/middleman/Middleman/Sitemap/Resource#url-instance_method :
+    # 'resource.path' is "The source path of this resource (relative to the source directory, without template extensions)."
+    # 'resource.destination_path', which is: "The output path in the build directory for this resource."
+    # 'resource.url' is based on 'resource.destination_path', but is further tweaked to optionally strip the index file and prefixed with any :http_prefix.
 
-        path_to_site_root = path_to_site_root config, current_page.path
-        resource_path = path_to_site_root + resource_path_segments
-                                           .push(resource_file_name)
-                                           .join("/")
+    # Calculates the path to the sought resource, taking in to account whether the site has been configured
+    # to generate relative or absolute links.
+    # Identifies whether the sought resource is an internal or external target: External targets are returned untouched. Path calculation is performed for internal targets.
+    # Works for both "Middleman::Sitemap::Resource" resources and plain strings (which may be passed from the site configuration when generating header links).
+    #
+    # @param [Object] config
+    # @param [Object] resource
+    # @param [Object] current_page
+    def get_path_to_resource(config, resource, current_page)
+      if resource.is_a?(Middleman::Sitemap::Resource)
+        config[:relative_links] ? get_resource_path_relative_to_current_page(config, current_page.path, resource.path) : resource.url
+      elsif external_url?(resource)
+        resource
+      elsif config[:relative_links]
+        get_resource_path_relative_to_current_page(config, current_page.path, resource)
       else
-        resource_path = resource.url
+        resource
       end
-      resource_path
     end
 
     def path_to_site_root(config, page_path)
@@ -26,5 +37,24 @@ module GovukTechDocs
       end
       path_to_site_root
     end
+
+  private
+
+    # Calculates the path to the sought resource, relative to the current page.
+    # @param [Object] config Middleman config.
+    # @param [String] current_page path of the current page, from the site root.
+    # @param [String] resource_path_from_site_root path of the sought resource, from the site root.
+    def get_resource_path_relative_to_current_page(config, current_page, resource_path_from_site_root)
+      path_segments = resource_path_from_site_root.split("/").reject(&:empty?)[0..-2]
+      path_file_name = resource_path_from_site_root.split("/")[-1]
+
+      path_to_site_root = path_to_site_root config, current_page
+      path_to_site_root + path_segments.push(path_file_name).join("/")
+    end
+
+    def external_url?(url)
+      uri = URI.parse(url)
+      uri.scheme || uri.to_s.split("/")[0]&.include?(".")
+    end
   end
 end

data/lib/govuk_tech_docs/redirects.rb

@@ -1,6 +1,6 @@
 module GovukTechDocs
   class Redirects
-    LEADING_SLASH = %r[\A\/].freeze
+    LEADING_SLASH = %r{\A/}.freeze
 
     def initialize(context)
       @context = context
@@ -11,7 +11,7 @@ module GovukTechDocs
 
       all_redirects.map do |from, to|
         # Middleman needs paths without leading slashes
-        [from.sub(LEADING_SLASH, ""), to: to.sub(LEADING_SLASH, "")]
+        [from.sub(LEADING_SLASH, ""), { to: to.sub(LEADING_SLASH, "") }]
       end
     end
 

data/lib/govuk_tech_docs/table_of_contents/heading.rb

@@ -9,14 +9,14 @@ module GovukTechDocs
       end
 
       def size
-        @element_name.scan(/h(\d)/) && $1 && Integer($1)
+        @element_name.scan(/h(\d)/) && ::Regexp.last_match(1) && Integer(::Regexp.last_match(1))
       end
 
       def href
         if @page_url != "" && size == 1
           @page_url
         else
-          @page_url + "#" + @attributes["id"]
+          "#{@page_url}##{@attributes['id']}"
         end
       end
 

data/lib/govuk_tech_docs/table_of_contents/heading_tree_renderer.rb

@@ -20,23 +20,23 @@ module GovukTechDocs
         output = ""
 
         if tree.heading
-          output += indentation + %{<a href="#{tree.heading.href}"><span>#{tree.heading.title}</span></a>\n}
+          output += indentation + %(<a href="#{tree.heading.href}"><span>#{tree.heading.title}</span></a>\n)
         end
 
         if tree.children.any? && level < @max_level
-          output += indentation + "<ul>\n" unless level.zero?
+          output += "#{indentation}<ul>\n" unless level.zero?
 
           tree.children.each do |child|
-            output += indentation + INDENTATION_INCREMENT + "<li>\n"
+            output += "#{indentation}#{INDENTATION_INCREMENT}<li>\n"
             output += render_tree(
               child,
               indentation: indentation + INDENTATION_INCREMENT * 2,
               level: level + 1,
             )
-            output += indentation + INDENTATION_INCREMENT + "</li>\n"
+            output += "#{indentation}#{INDENTATION_INCREMENT}</li>\n"
           end
 
-          output += indentation + "</ul>\n" unless level.zero?
+          output += "#{indentation}</ul>\n" unless level.zero?
         end
 
         output

data/lib/govuk_tech_docs/table_of_contents/helpers.rb

@@ -32,7 +32,7 @@ module GovukTechDocs
         headings = HeadingsBuilder.new(html, url).headings
 
         if headings.none? { |heading| heading.size == 1 }
-          raise "No H1 tag found. You have to at least add one H1 heading to the page: " + url
+          raise "No H1 tag found. You have to at least add one H1 heading to the page: #{url}"
         end
 
         tree = HeadingTreeBuilder.new(headings).tree
@@ -67,12 +67,12 @@ module GovukTechDocs
             if config[:http_prefix].end_with?("/")
               config[:http_prefix]
             else
-              config[:http_prefix] + "/"
+              "#{config[:http_prefix]}/"
             end
 
           link_value = get_path_to_resource(config, resource, current_page)
           if resource.children.any? && resource.url != home_url
-            output += %{<li><a href="#{link_value}"><span>#{resource.data.title}</span></a>\n}
+            output += %(<li><a href="#{link_value}"><span>#{resource.data.title}</span></a>\n)
             output += render_page_tree(resource.children, current_page, config, current_page_html)
             output += "</li>\n"
           else

data/lib/govuk_tech_docs/version.rb

@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "3.3.1".freeze
+  VERSION = "3.4.0".freeze
 end

data/lib/govuk_tech_docs.rb

@@ -86,8 +86,8 @@ module GovukTechDocs
       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,
+          "/#{current_page.path}" == page_path,
+          !current_page.data.parent.nil? && current_page.data.parent.to_s == page_path,
         ].any?
       end
     end
@@ -109,9 +109,9 @@ module GovukTechDocs
         search.resources = [""]
 
         search.fields = {
-          title:   { boost: 100, store: true, required: true },
+          title: { boost: 100, store: true, required: true },
           content: { boost: 50, store: true },
-          url:     { index: false, store: true },
+          url: { index: false, store: true },
         }
 
         search.pipeline_remove = %w[stemmer stopWordFilter]

data/lib/source/layouts/_footer.erb

@@ -6,7 +6,7 @@
         <ul class="govuk-footer__inline-list">
           <% config[:tech_docs][:footer_links].each do |title, path| %>
             <li class="govuk-footer__inline-list-item">
-              <a class="govuk-footer__link" href="<%= url_for path %>"><%= title %></a>
+              <a class="govuk-footer__link" href="<%= get_path_to_resource config, path, current_page %>"><%= title %></a>
             </li>
           <% end %>
         </ul>

data/lib/source/layouts/_header.erb

@@ -2,7 +2,7 @@
   <div class="govuk-header__container govuk-header__container--full-width">
     <div class="govuk-header__logo">
       <% if config[:tech_docs][:service_link] %>
-      <a href="<%= url_for config[:tech_docs][:service_link] %>" class="govuk-header__link govuk-header__link--homepage">
+      <a href="<%= get_path_to_resource config, config[:tech_docs][:service_link], current_page %>" class="govuk-header__link govuk-header__link--homepage">
       <% else %>
       <span class="govuk-header__link govuk-header__link--homepage">
       <% end %>
@@ -46,7 +46,7 @@
         <ul id="navigation" class="govuk-header__navigation-list">
           <% config[:tech_docs][:header_links].each do |title, path| %>
             <li class="govuk-header__navigation-item<% if active_page(path) %> govuk-header__navigation-item--active<% end %>">
-              <a class="govuk-header__link" href="<%= url_for path %>"><%= title %></a>
+              <a class="govuk-header__link" href="<%= get_path_to_resource config, path, current_page %>"><%= title %></a>
             </li>
           <% end %>
         </ul>