govuk_tech_docs 3.0.1 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 306970ce3c2eedf60e681b68a6a0539480d8a4626ff4bd3f57207fa32cb2a06c
-  data.tar.gz: 2d8ccd150d9e394a9c54ee3a33bd0c424ecd71848022d00bbc7ce7f66c1cfc24
+  metadata.gz: 79d38e9facb7df0c0a08151b51ce448759efa6e61bcf8ec0c5e6efb0b4e92332
+  data.tar.gz: 0a47d960ef878bf334104c7f0ff3e3e07e0411e3b12d061dc72ca4c474c988a1
 SHA512:
-  metadata.gz: 2efb012ebfdf219f6f08fb91130189fb23368731a31371f806fb16727b627f7ba7c3f8fa0894afc0e10af879adb950eb1b2d7dfca49f98b0fa2fe6eabc129a74
-  data.tar.gz: e34554e67b183255fa3f20fb2dcb95e4c3af042de317f7735c82e5c3a988524de7c4e0e12b58bac20f9bdf770a9bd2e556bea6febb0e62ecd560f04cdd885782
+  metadata.gz: 8a6e9076fc8b8a6ade8cca61c139256b6f8a455e851c64e68132ee25e9ec0fe09876e3cfb1bf813297779d376e91ac0f1abd49cd30319944249c6fff4117c902
+  data.tar.gz: 98748cf227f452712eb2ffcd780d89a7b56b9beed437f0a775adb1eba81a0acfca7de59c89db7437484a8f8e9e63a1e71c513475f1f55affc8ff48b5da2fe64a

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 3.2.1
+
+### Fixes
+
+- [#296: Fix Nokogiri Node.new deprecation warnings](https://github.com/alphagov/tech-docs-gem/pull/296) (thanks [@timja](https://github.com/timja))
+
+## 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
+
+There are some steps you should follow as the Technical Documentation Template (TDT) now uses GOV.UK Frontend 4.0.0. 
+
+1. Update your documentation site to use the latest template version. You can [follow the TDT guidance on using the latest template version](https://tdt-documentation.london.cloudapps.digital/maintain_project/use_latest_template/).
+2. Check your documentation site displays correctly. If your site does not display correctly, you can refer to the [GOV.UK Frontend 4.0.0 release note](https://github.com/alphagov/govuk-frontend/releases/tag/v4.0.0) for more information. 
+
 ## 3.0.1
 
 ### Fixes

data/example/source/code.html.md

@@ -10,32 +10,9 @@ A paragraph with a `code` element within it.
 
 An example of a table with a `code` element within it.
 
-<div class="table-container">
-  <table>
-    <thead>
-      <tr>
-        <th style="text-align:left">httpResult</th>
-        <th style="text-align:left">Message</th>
-        <th style="text-align:left">How to fix</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td style="text-align:left"><code>400</code></td>
-        <td style="text-align:left">
-          <code>[{</code>
-          <br />
-          <code>"error": "BadRequestError",</code>
-          <br />
-          <code>"message": "Can't send to this recipient using a team-only API key"</code>
-          <br />
-          <code>]}</code>
-        </td>
-        <td style="text-align:left">Use the correct type of API key</td>
-      </tr>
-    </tbody>
-  </table>
-</div>
+| httpResult | Message | How to fix |
+| -          | -       | -          |
+| `400`      | `[{`<br>`"error": "BadRequestError",`<br>`"message": "Can't send to this recipient using a team-only API key"`<br>`]}` | Use the correct type of API key |
 
 An example of a code block with a long line length
 

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/tech_docs_html_renderer.rb

@@ -69,7 +69,7 @@ module GovukTechDocs
         first_child.content = leading_text.sub(/# */, "")
       end
 
-      tr = Nokogiri::XML::Node.new "tr", fragment
+      tr = Nokogiri::XML::Node.new "tr", fragment.document
       tr.children = fragment.children
 
       tr.to_html
@@ -95,9 +95,9 @@ module GovukTechDocs
         # be `defined?`, so we can jump straight to rendering HTML ourselves.
 
         fragment = Nokogiri::HTML::DocumentFragment.parse("")
-        pre = Nokogiri::XML::Node.new "pre", fragment
+        pre = Nokogiri::XML::Node.new "pre", fragment.document
         pre["tabindex"] = "0"
-        code = Nokogiri::XML::Node.new "code", fragment
+        code = Nokogiri::XML::Node.new "code", fragment.document
         code["class"] = lang
         code.content = text
         pre.add_child code

data/lib/govuk_tech_docs/version.rb

@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "3.0.1".freeze
+  VERSION = "3.2.1".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/_header.erb

@@ -41,9 +41,9 @@
     </div>
     <% if config[:tech_docs][:header_links] %>
     <div class="govuk-header__content">
-      <button type="button" class="govuk-header__menu-button govuk-js-header-toggle" aria-controls="navigation" aria-label="Show or hide Top Level Navigation">Menu</button>
-      <nav>
-        <ul id="navigation" class="govuk-header__navigation govuk-header__navigation--end" aria-label="Top Level Navigation">
+      <nav class="govuk-header__navigation govuk-header__navigation--end" aria-label="Menu">
+        <button type="button" class="govuk-header__menu-button govuk-js-header-toggle" aria-controls="navigation" aria-label="Show or hide menu">Menu</button>
+        <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>

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

data/lib/source/layouts/core.erb

@@ -27,7 +27,7 @@
 
     <div class="app-pane">
       <div class="app-pane__header toc-open-disabled">
-        <a href="#content" class="govuk-skip-link">Skip to main content</a>
+        <a href="#content" class="govuk-skip-link" data-module="govuk-skip-link">Skip to main content</a>
 
         <%= partial 'layouts/header' %>
       </div>