govuk_tech_docs 2.4.2 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b52d6e8aa198588eb1483b68997af30d2ead1179addc62110cfdab7d1d117920
-  data.tar.gz: ae9fb52fb1ca0929cc5be15f74ca32d6acd159eb248f397b976f963d8a00ca76
+  metadata.gz: b05aaaeb08b75633793f5ede8102ef35d54cedbe6bc419b9fe262a3596d6cfef
+  data.tar.gz: 30ab85794e056634591d692999364da7644908653e06d2707aa15eeff9b5bfea
 SHA512:
-  metadata.gz: f0b288f32a3adf1c974d525186efd8839b71372eed7425a1e31dc13f6a27b840e00536d481dca6218d303bdfea281299672b409080a53ab40c7b483968cfda84
-  data.tar.gz: 18de4113f809ff2c8ef69f399d20e0781241242eaf0660cd2668d023d3e136114abada7e783087b4bf8e19149c4d1ba570fe161fb7798ec33ff49e8bbc1de6dc
+  metadata.gz: 406187054e9b14fd631fb56a2602f8c607ab2abfe8be466673ffee99fba6451ebe684dca40e53270b66b5b1a6b12142336ad26124335b33b02205e13005290e8
+  data.tar.gz: fc0afcd3567241e487bb75fbfebb26561ee8b6c9dd0a50d5f2d8252ea2d8a95c71976ae2540ff1f58e2d89886234c25b6d6b726fb74e618a1fba05ae97b0303d

data/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,13 @@
+<!--
+Please fill in the sections below.
+
+After you submit your issue, the technical writing team from the Central Digital and Data Office (CDDO) will discuss and prioritise it at our fortnightly triage meeting. We’ll then let you know if and when we’ll move it forward.
+-->
+
+## What should change
+
+<!-- What would fix the issue? Is this something you think should behave differently, or something that you currently cannot do? -->
+
+## User need
+
+<!-- Do you have evidence that this meets the needs of users? Let us know about any user research or testing you’ve done. -->

data/.github/pull_request_template.md

@@ -1 +1,14 @@
-⚠️ Don't forget to update the gem version in the [CHANGELOG](https://github.com/alphagov/tech-docs-gem/blob/master/CHANGELOG.md) before merging! When you're ready to release bump [version file](https://github.com/alphagov/tech-docs-gem/blob/master/lib/govuk_tech_docs/version.rb) and generate a tag. ⚠️
+<!--
+## Please fill in the sections below
+
+After you submit your pull request, the technical writing team from the Central Digital and Data Office (CDDO) will discuss and prioritise it at our fortnightly triage meeting. We’ll then let you know if and when we’ll move it forward.
+-->
+
+## What’s changed
+
+<!-- What are you trying to do? Is this something that changes how the Tech Docs Template behaves, or is it fixing a bug? -->
+
+
+## Identifying a user need
+
+<!-- Do you have evidence that this meets the needs of users? Let us know about any user research or testing you’ve done. -->

data/.github/workflows/publish.yaml

@@ -0,0 +1,76 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+concurrency: rubygems
+
+jobs:
+  pre:
+    name: Pre-flight checks
+    runs-on: ubuntu-latest
+    outputs:
+      go: ${{ steps.gem_version.outputs.new_version }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: ruby/setup-ruby@v1
+
+      - 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"
+
+          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"
+          else
+            echo "::set-output name=new_version::true"
+          fi
+
+  deploy:
+    name: Publish Ruby Gem
+    environment: rubygems
+    permissions:
+      contents: write  # needed to be able to tag the release
+    runs-on: ubuntu-latest
+    needs: pre
+    if: ${{ needs.pre.outputs.go == 'true' }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-node@v2
+        with:
+          cache: 'npm'
+          node-version: '14'
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Publish
+        env:
+          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          mkdir -p ~/.gem
+
+          cat << EOF > ~/.gem/credentials
+          ---
+          :rubygems_api_key: ${RUBYGEMS_API_KEY}
+          EOF
+
+          chmod 0600 ~/.gem/credentials
+
+          # tag will be associated with github-actions bot user, see
+          # https://github.community/t/github-actions-bot-email-address/17204
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          bundle exec rake release

data/.github/workflows/test.yaml

@@ -0,0 +1,23 @@
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14'
+          cache: 'npm'
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake

data/.nvmrc

@@ -1 +1 @@
-10
+14

data/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+## 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
+
+We’ve made the following fixes to the tech docs gem in [pull request #281: Don't break TOC when OpenAPI description includes headers](https://github.com/alphagov/tech-docs-gem/pull/281): 
+
+* we now render OpenAPI Markdown with the same Markdown renderer as other documents
+* table of contents (TOC) uses `TechDocsHTMLRenderer` to render the headings with IDs
+
+Thanks to [@jamietanna](https://github.com/jamietanna) for contributing to this issue and its solution.
+
+## 3.0.0
+
+### Breaking changes
+
+The search user experience is now more accessible for screenreader users. Search results are now on a separate page instead of a modal window.
+
+Users can no longer see search results as they type. They must press the Return key or select the search button to see the search results page.
+
+This was added in [pull request #263: Change search to only show results after submit](https://github.com/alphagov/tech-docs-gem/pull/263).
+
+### Fixes
+
+- [#265: Fix mark styles in Windows High Contrast Mode](https://github.com/alphagov/tech-docs-gem/pull/265)
+
+## 2.4.3
+
+- [#236: Fix search 'autocomplete' behaviour](https://github.com/alphagov/tech-docs-gem/pull/236)
+- [#203: Update vendored javascripts](https://github.com/alphagov/tech-docs-gem/pull/203)
+
 ## 2.4.2
 
 - [#251 Fix missing `<ul>` in single page navigation](https://github.com/alphagov/tech-docs-gem/pull/251)

data/README.md

@@ -9,7 +9,7 @@ To find out more about setting up and managing content for a website using this
 
 Everybody who uses this project is encouraged to contribute.
 
-You can find out more about contributing to this project from the[CONTRIBUTING.md file](CONTRIBUTING.md).
+Find out how to [contribute](https://tdt-documentation.london.cloudapps.digital/support/#contribute).
 
 ## GOV.UK frontend
 
@@ -34,6 +34,8 @@ gem 'govuk_tech_docs', path: '../tech-docs-gem'
 
 To preview your documentation changes locally, see the [Tech Docs Template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation).
 
+If you experience [the FFI gem issue for Mojave users](https://github.com/alphagov/tech-docs-gem/issues/254), you should refer to this [list of possible fixes](#issue-with-ffi-on-osx-mohave).
+
 ### Use the example in this repo
 
 To start the example in this repo, run:
@@ -46,6 +48,8 @@ bundle exec middleman server
 
 See your website on `http://localhost:4567` in your browser.
 
+If you experience [the FFI gem issue for Mojave users](https://github.com/alphagov/tech-docs-gem/issues/254), you should refer to this [list of possible fixes](#issue-with-ffi-on-osx-mohave).
+
 For more information on previewing your documentation locally, see the [Tech Docs template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation).
 
 ## Tests
@@ -63,6 +67,16 @@ To run the tests and see the results in your terminal, run:
 bundle exec rake jasmine:ci
 ```
 
+## Issue with FFI on OSX Mojave
+
+Users on OSX Mojave (10.14) may get this error when running `bundle exec middleman serve` on apps that use this gem.
+
+There are 3 possible ways to solve this. From best to worst, you can:
+
+* upgrade to macOS 10.15 (Catalina) or higher
+* tell rubygems not to use the system ffi by running `gem install ffi -- --disable-system-libffi` in the command line when the error shows
+* pin the ffi version back to 1.12.2 by editing the Gemfile of your app
+
 ## Releasing new versions
 
 To release a new version, create a new pull request (PR) that updates [version.rb](lib/govuk_tech_docs/version.rb) and [CHANGELOG.md](CHANGELOG.md).

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

@@ -6,35 +6,48 @@
   Modules.Search = function Search () {
     var s = this
     var $html = $('html')
-    var $tocNav
     var $searchForm
     var $searchLabel
     var $searchInput
     var $searchResults
     var $searchResultsTitle
     var $searchResultsWrapper
-    var $searchResultsClose
+    var $searchHelp
     var results
     var query
-    var queryTimer
     var maxSearchEntries = 20
 
     this.start = function start ($element) {
       $searchForm = $element.find('form')
       $searchInput = $element.find('#search')
       $searchLabel = $element.find('.search__label')
-      $searchResultsWrapper = $element.find('.search-results')
+      $searchResultsWrapper = $('#search-results')
       $searchResults = $searchResultsWrapper.find('.search-results__content')
       $searchResultsTitle = $searchResultsWrapper.find('.search-results__title')
-      $searchResultsClose = $searchResultsWrapper.find('.search-results__close')
-      $tocNav = $('#toc')
-      s.downloadSearchIndex()
-      attach()
+      $searchHelp = $('#search-help')
+
+      changeSearchAction()
       changeSearchLabel()
+
+      // Only do searches on the search page
+      if (s.isOnSearchPage()) {
+        s.downloadSearchIndex()
+        $html.addClass('has-search-results-open')
+
+        if (window.location.search) {
+          query = s.getQuery()
+          if (query) {
+            $searchInput.val(query)
+            doSearch(query)
+            doAnalytics()
+            document.title = query + ' - ' + document.title
+          }
+        }
+      }
     }
 
     this.downloadSearchIndex = function downloadSearchIndex () {
-      updateTitle('Loading search index')
+      updateTitle('Loading search results')
       $.ajax({
         url: '/search.json',
         cache: true,
@@ -48,46 +61,45 @@
       })
     }
 
-    function attach () {
-      // Search functionality on search text input
-      $searchInput.on('input', function (e) {
-        e.preventDefault()
-        query = $(this).val()
-        s.search(query, function (r) {
-          results = r
-          renderResults(query)
-          updateTitle()
-        })
-        if (window.ga) {
-          window.clearTimeout(queryTimer)
-          queryTimer = window.setTimeout(sendQueryToAnalytics, 1000)
-        }
-      })
+    function changeSearchAction () {
+      // 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.find('input[name="as_sitesearch"]').remove()
+    }
 
-      // Set focus on the first search result instead of submiting the search
-      // form to Google
-      $searchForm.on('submit', function (e) {
-        e.preventDefault()
-        showResults()
-        var $firstResult = $searchResults.find('.search-result__title a').first()
-        if ($firstResult.length) {
-          $firstResult.focus()
-        } else {
-          // if there are no results, show the "0 results" state
-          results = []
-          updateTitle()
-        }
-      })
+    function changeSearchLabel () {
+      $searchLabel.text('Search this documentation')
+    }
 
-      // Closing the search results, move focus back to the search input
-      $searchResultsClose.on('click', function (e) {
-        e.preventDefault()
-        $searchInput.focus()
-        hideResults()
+    this.isOnSearchPage = function isOnSearchPage () {
+      return Boolean(window.location.pathname.match(/\/search(\/|\/index.html)?$/))
+    }
+
+    this.getQuery = function getQuery () {
+      var query = decodeURIComponent(
+        window.location.search
+          .match(/q=([^&]*)/)[1]
+          .replace(/\+/g, ' ')
+      )
+      return query
+    }
+
+    function doSearch (query) {
+      s.search(query, function (r) {
+        results = r
+        renderResults(query)
+        updateTitle()
       })
+    }
 
-      // Attach analytics events to search result clicks
+    // TODO: remove this and sendQueryToAnalytics in a future breaking release
+    function doAnalytics () {
       if (window.ga) {
+        sendQueryToAnalytics()
+
+        // Attach analytics events to search result clicks
         $searchResults.on('click', '.search-result__title a', function () {
           var href = $(this).attr('href')
           ga('send', {
@@ -99,15 +111,6 @@
           })
         })
       }
-
-      // When selecting navigation link, close the search results.
-      $('#toc').on('click', 'a', function (e) {
-        hideResults()
-      })
-    }
-
-    function changeSearchLabel () {
-      $searchLabel.text('Search this documentation')
     }
 
     function getResults (query) {
@@ -122,7 +125,6 @@
 
     this.search = function search (query, callback) {
       if (query === '') {
-        hideResults()
         return
       }
       showResults()
@@ -192,23 +194,14 @@
     function updateTitle (text) {
       if (typeof text === 'undefined') {
         var count = results.length
-        var resultsText = count + ' results'
+        var resultsText = 'Search - ' + query + ' - ' + count + ' results'
       }
       $searchResultsTitle.text(text || resultsText)
     }
 
     function showResults () {
-      $searchResultsWrapper.addClass('is-open')
-        .attr('aria-hidden', 'false')
-      $html.addClass('has-search-results-open')
-      $tocNav.addClass('search-results-open')
-    }
-
-    function hideResults () {
-      $searchResultsWrapper.removeClass('is-open')
-        .attr('aria-hidden', 'true')
-      $html.removeClass('has-search-results-open')
-      $tocNav.removeClass('search-results-open')
+      $searchResultsWrapper.removeAttr('hidden')
+      $searchHelp.attr('hidden', 'true')
     }
 
     function sendQueryToAnalytics () {

data/lib/assets/javascripts/_modules/table-of-contents.js

@@ -69,7 +69,6 @@
 
     function closeNavigation () {
       $html.removeClass('toc-open')
-      $html.removeClass('has-search-results-open')
 
       toggleBackgroundVisiblity(true)
       updateAriaAttributes()