govuk_tech_docs 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b05aaaeb08b75633793f5ede8102ef35d54cedbe6bc419b9fe262a3596d6cfef
-  data.tar.gz: 30ab85794e056634591d692999364da7644908653e06d2707aa15eeff9b5bfea
+  metadata.gz: 06ad063ddc3de387b2bae379df43d4ecd6996a42bdc1f0472e2eb46b404b5701
+  data.tar.gz: 23b17f1d49d77303d7acb06be0ee2f30cd8ec9b40407b18689696008bf594b89
 SHA512:
-  metadata.gz: 406187054e9b14fd631fb56a2602f8c607ab2abfe8be466673ffee99fba6451ebe684dca40e53270b66b5b1a6b12142336ad26124335b33b02205e13005290e8
-  data.tar.gz: fc0afcd3567241e487bb75fbfebb26561ee8b6c9dd0a50d5f2d8252ea2d8a95c71976ae2540ff1f58e2d89886234c25b6d6b726fb74e618a1fba05ae97b0303d
+  metadata.gz: dfff9af883e1eb613f704789bd55f65947309e5df3a7a1d1280f4a28483a55d38200108d9808279d3985e2fd75bdc86adccea94520bb7469a78cdfa654def53c
+  data.tar.gz: '09ae4a42091646b3850af6e4db030a0912e48a10df7b0db296621cdaa58c5df236c17399374201fe2f4af4bd38ce9525837a0811145cfea5fa380b70c5836541'

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 3.2.0
+
+### New features
+
+You can now [configure your Tech Docs Template (TDT) to build your documentation site to use relative links to pages and assets](https://tdt-documentation.london.cloudapps.digital/configure_project/global_configuration/#build-your-site-using-relative-links).
+
+Thanks [@eddgrant](https://github.com/eddgrant) for contributing this feature and the associated fixes.
+
+This change was introduced in [pull request #291: Support sites deployed on paths other than "/" (by generating relative links)](https://github.com/alphagov/tech-docs-gem/pull/291). 
+
 ## 3.1.0
 
 ### New features

data/lib/assets/javascripts/_modules/collapsible-navigation.js

@@ -57,25 +57,31 @@
       $toggleLabel.text(setOpen ? 'Collapse ' + $heading.text() : 'Expand ' + $heading.text())
     }
 
+    /**
+     * Returns an absolute pathname to $target by combining it with window.location.href
+     * @param $target The target whose pathname to return. This may be an anchor with an absolute or relative href.
+     * @returns {string} The absolute pathname of $target
+     */
+    function getAbsolutePath ($target) {
+      return new URL($target.attr('href'), window.location.href).pathname
+    }
+
     function openActiveHeading () {
       var $activeElement
       var currentPath = window.location.pathname
-      var isActiveTrail = '[href*="' + currentPath + '"]'
-      // Add an exception for the root page, as every href includes /
-      if (currentPath === '/') {
-        isActiveTrail = '[href="' + currentPath + window.location.hash + '"]'
-      }
       for (var i = $topLevelItems.length - 1; i >= 0; i--) {
         var $element = $($topLevelItems[i])
         var $heading = $element.find('> a')
         // Check if this item href matches
-        if ($heading.is(isActiveTrail)) {
+        if (getAbsolutePath($heading) === currentPath) {
           $activeElement = $element
           break
         }
         // Otherwise check the children
         var $children = $element.find('li > a')
-        var $matchingChildren = $children.filter(isActiveTrail)
+        var $matchingChildren = $children.filter(function (_) {
+          return getAbsolutePath($(this)) === currentPath
+        })
         if ($matchingChildren.length) {
           $activeElement = $element
           break

data/lib/assets/javascripts/_modules/in-page-navigation.js

@@ -70,13 +70,18 @@
     function highlightActiveItemInToc (fragment) {
       // Navigation items for single page navigation don't necessarily include the path name, but
       // navigation items for multipage navigation items do include it. This checks for either case.
-      var $activeTocItem = $tocItems.filter(
-        '[href="' + window.location.pathname + fragment + '"],[href="' + fragment + '"]'
-      )
+      var $activeTocItem = $tocItems.filter(function (_) {
+        var url = new URL($(this).attr('href'), window.location.href)
+        return url.href === window.location.href
+      })
+
       // Navigation items with children don't contain fragments in their url
       // Check to see if any nav items contain just the path name.
       if (!$activeTocItem.get(0)) {
-        $activeTocItem = $tocItems.filter('[href="' + window.location.pathname + '"]')
+        $activeTocItem = $tocItems.filter(function (_) {
+          var url = new URL($(this).attr('href'), window.location.href)
+          return url.hash === '' && url.pathname === window.location.pathname
+        })
       }
       if ($activeTocItem.get(0)) {
         $tocItems.removeClass('toc-link--in-view')

data/lib/assets/javascripts/_modules/search.js

@@ -16,6 +16,7 @@
     var results
     var query
     var maxSearchEntries = 20
+    var pathToSiteRoot
 
     this.start = function start ($element) {
       $searchForm = $element.find('form')
@@ -25,6 +26,7 @@
       $searchResults = $searchResultsWrapper.find('.search-results__content')
       $searchResultsTitle = $searchResultsWrapper.find('.search-results__title')
       $searchHelp = $('#search-help')
+      pathToSiteRoot = $element.data('pathToSiteRoot')
 
       changeSearchAction()
       changeSearchLabel()
@@ -38,7 +40,7 @@
           query = s.getQuery()
           if (query) {
             $searchInput.val(query)
-            doSearch(query)
+            doSearch(query, pathToSiteRoot)
             doAnalytics()
             document.title = query + ' - ' + document.title
           }
@@ -49,7 +51,7 @@
     this.downloadSearchIndex = function downloadSearchIndex () {
       updateTitle('Loading search results')
       $.ajax({
-        url: '/search.json',
+        url: pathToSiteRoot + 'search.json',
         cache: true,
         method: 'GET',
         success: function (data) {
@@ -65,7 +67,7 @@
       // We need JavaScript to do search, so if JS is not available the search
       // input sends the query string to Google. This JS function changes the
       // input to instead send it to the search page.
-      $searchForm.prop('action', '/search')
+      $searchForm.prop('action', pathToSiteRoot + 'search/index.html')
       $searchForm.find('input[name="as_sitesearch"]').remove()
     }
 
@@ -86,10 +88,10 @@
       return query
     }
 
-    function doSearch (query) {
+    function doSearch (query, pathToSiteRoot) {
       s.search(query, function (r) {
         results = r
-        renderResults(query)
+        renderResults(query, pathToSiteRoot)
         updateTitle()
       })
     }
@@ -138,7 +140,7 @@
       callback(getResults(query))
     }
 
-    function renderResults (query) {
+    function renderResults (query, pathToSiteRoot) {
       var output = ''
       if (results.length === 0) {
         output += '<p>Nothing found</p>'
@@ -149,7 +151,9 @@
         var content = s.processContent(result.content, query)
         output += '<li class="search-result">'
         output += '<h3 class="search-result__title">'
-        output += '<a href="' + result.url + '">'
+        var pagePathWithoutLeadingSlash = result.url.startsWith('/') ? result.url.slice(1) : result.url
+        var url = pathToSiteRoot.startsWith('.') ? pathToSiteRoot + pagePathWithoutLeadingSlash : '/' + pagePathWithoutLeadingSlash
+        output += '<a href="' + url + '">'
         output += result.title
         output += '</a>'
         output += '</h3>'

data/lib/assets/stylesheets/_govuk_tech_docs.scss

@@ -1,4 +1,4 @@
-$govuk-assets-path: "/assets/govuk/assets/";
+$govuk-assets-path: "/assets/govuk/assets/" !default;
 
 // Include only the bits of GOV.UK Frontend we need
 $govuk-new-link-styles: true;

data/lib/assets/stylesheets/modules/_anchored-heading.scss

@@ -18,12 +18,12 @@
     text-decoration: none;
     text-indent: -9999em;
 
-    background-image: url('/images/anchored-heading-icon.png');
+    background-image: image-url('/images/anchored-heading-icon.png');
     background-repeat: no-repeat;
     background-position: center center;
 
     @include govuk-device-pixel-ratio {
-      background-image: url('/images/anchored-heading-icon-2x.png');
+      background-image: image-url('/images/anchored-heading-icon-2x.png');
       background-size: $icon-width $icon-height;
     }
 

data/lib/assets/stylesheets/modules/_search.scss

@@ -36,7 +36,7 @@ $input-size: 40px;
   padding: 0;
   width: $input-size;
   height: 100%;
-  background-image: url('/images/search-button.png');
+  background-image: image-url('/images/search-button.png');
   background-repeat: no-repeat;
   background-position: 2px 50%;
   text-indent: -5000px;
@@ -104,7 +104,7 @@ $input-size: 40px;
       left: -9px;
       width: 10px;
       height: 20px;
-      background: no-repeat url('/images/search-result-caret.svg') center right;
+      background: no-repeat image-url('/images/search-result-caret.svg') center right;
       background-size: contain;
     }
   }

data/lib/assets/stylesheets/modules/_toc.scss

@@ -152,12 +152,12 @@
           height: 20px;
           float: right;
 
-          background-image: url('/images/govuk-icn-numbered-list.png');
+          background-image: image-url('/images/govuk-icn-numbered-list.png');
           background-repeat: no-repeat;
           background-position: left center;
 
           @include govuk-device-pixel-ratio {
-            background-image: url('/images/govuk-icn-numbered-list@2x.png');
+            background-image: image-url('/images/govuk-icn-numbered-list@2x.png');
             background-size: 20px 20px;
           }
         }
@@ -178,12 +178,12 @@
         height: 20px;
         cursor: pointer;
 
-        background-image: url('/images/govuk-icn-close.png');
+        background-image: image-url('/images/govuk-icn-close.png');
         background-repeat: no-repeat;
         background-position: left center;
 
         @include govuk-device-pixel-ratio {
-          background-image: url('/images/govuk-icn-close@2x.png');
+          background-image: image-url('/images/govuk-icn-close@2x.png');
           background-size: 20px 20px;
         }
 

data/lib/govuk_tech_docs/pages.rb

@@ -1,10 +1,12 @@
 module GovukTechDocs
   class Pages
+    include GovukTechDocs::PathHelpers
     attr_reader :sitemap
 
-    def initialize(sitemap, config)
+    def initialize(sitemap, config, current_page)
       @sitemap = sitemap
       @config = config
+      @current_page = current_page
     end
 
     def to_json(*_args)
@@ -18,7 +20,7 @@ module GovukTechDocs
         review = PageReview.new(page, @config)
         {
           title: page.data.title,
-          url: "#{@config[:tech_docs][:host]}#{page.url}",
+          url: get_path_to_resource(@config, page, @current_page).to_s,
           review_by: review.review_by,
           owner_slack: review.owner_slack,
         }

data/lib/govuk_tech_docs/path_helpers.rb

@@ -0,0 +1,30 @@
+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]
+
+        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("/")
+      else
+        resource_path = resource.url
+      end
+      resource_path
+    end
+
+    def path_to_site_root(config, page_path)
+      if config[:relative_links]
+        number_of_ascents_to_site_root = page_path.to_s.split("/").reject(&:empty?)[0..-2].length
+        ascents = number_of_ascents_to_site_root.zero? ? ["."] : number_of_ascents_to_site_root.times.collect { ".." }
+        path_to_site_root = ascents.join("/").concat("/")
+      else
+        middleman_http_prefix = config[:http_prefix]
+        path_to_site_root = middleman_http_prefix.end_with?("/") ? middleman_http_prefix : "#{middleman_http_prefix}/"
+      end
+      path_to_site_root
+    end
+  end
+end

data/lib/govuk_tech_docs/table_of_contents/helpers.rb

@@ -1,3 +1,4 @@
+require "govuk_tech_docs/path_helpers"
 require "govuk_tech_docs/table_of_contents/heading_tree_builder"
 require "govuk_tech_docs/table_of_contents/heading_tree_renderer"
 require "govuk_tech_docs/table_of_contents/heading_tree"
@@ -7,6 +8,8 @@ require "govuk_tech_docs/table_of_contents/headings_builder"
 module GovukTechDocs
   module TableOfContents
     module Helpers
+      include GovukTechDocs::PathHelpers
+
       def single_page_table_of_contents(html, url: "", max_level: nil)
         output = "<ul>\n"
         output += list_items_from_headings(html, url: url, max_level: max_level)
@@ -48,11 +51,7 @@ module GovukTechDocs
 
           # Reuse the generated content for the active page
           # If we generate it twice it increments the heading ids
-          content = if current_page.url == resource.url && current_page_html
-                      current_page_html
-                    else
-                      resource.render(layout: false)
-                    end
+          content = current_page.url == resource.url && current_page_html ? current_page_html : resource.render(layout: false)
           # Avoid redirect pages
           next if content.include? "http-equiv=refresh"
 
@@ -71,15 +70,16 @@ module GovukTechDocs
               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="#{resource.url}"><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
             output +=
               list_items_from_headings(
                 content,
-                url: resource.url,
+                url: link_value,
                 max_level: config[:tech_docs][:max_toc_heading_level],
               )
           end

data/lib/govuk_tech_docs/version.rb

@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "3.1.0".freeze
+  VERSION = "3.2.0".freeze
 end

data/lib/govuk_tech_docs.rb

@@ -67,6 +67,7 @@ module GovukTechDocs
     context.activate :api_reference
 
     context.helpers do
+      include GovukTechDocs::PathHelpers
       include GovukTechDocs::TableOfContents::Helpers
       include GovukTechDocs::ContributionBanner
 

data/lib/source/api/pages.json.erb

@@ -1 +1 @@
-<%= GovukTechDocs::Pages.new(sitemap, config).to_json %>
+<%= GovukTechDocs::Pages.new(sitemap, config, current_page).to_json %>

data/lib/source/layouts/_search.erb

@@ -1,5 +1,5 @@
 <% if config[:tech_docs][:enable_search] %>
-<div class="search" data-module="search">
+<div class="search" data-module="search" data-path-to-site-root="<%= path_to_site_root config, current_page.path %>">
   <form action="https://www.google.co.uk/search" method="get" role="search" class="search__form govuk-!-margin-bottom-4">
     <input type="hidden" name="as_sitesearch" value="<%= config[:tech_docs][:host] %>"/>
     <label class="govuk-label search__label" for="search" aria-hidden="true">

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_tech_docs
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-20 00:00:00.000000000 Z
+date: 2022-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: autoprefixer-rails
@@ -360,6 +360,7 @@ files:
 - lib/govuk_tech_docs/meta_tags.rb
 - lib/govuk_tech_docs/page_review.rb
 - lib/govuk_tech_docs/pages.rb
+- lib/govuk_tech_docs/path_helpers.rb
 - lib/govuk_tech_docs/redirects.rb
 - lib/govuk_tech_docs/table_of_contents/heading.rb
 - lib/govuk_tech_docs/table_of_contents/heading_tree.rb