Enable publishing via github pages, without requiring a dedicated domain name

[digitalronin]

We use the tech-docs gem at the MoJ for some of our documentation sites, e.g.

• https://user-guide.cloud-platform.service.justice.gov.uk
• https://runbooks.cloud-platform.service.justice.gov.uk

Both of those are published via github pages, with dedicated domain names.

It would be good if we could publish tech-docs sites using github pages without needing a separate domain name for each site, and just using the "default" URL from github pages, e.g. https://ministryofjustice.github.io/technical-guidance/

The search feature of the tech-docs gem, which is something we find extremely useful, doesn't work by default, because of some baked-in assumptions:

• When creating the index, the URL to each page is assumed to be / plus the relative path to the file
• The path to download search.json when carrying out a search is hard-coded to /search.json

Both of these could be fixed by changes to two gems:

In govuk_tech_docs-2.0.13/lib/assets/javascripts/_modules/search.js:

• Change the filename to search.js.erb and change line 37 from:

        url: '/search.json',

to

        url: '<%= ENV["ROOT_DOCPATH"] %>/search.json',

The switch to ".erb" causes sprockets pre-process the file using erb when creating the application.js file, so setting ROOT_DOCPATH to "/technical-guidance" means the search function can download the JSON data when the site is published.

In middleman-search-gds-0.11.1/lib/middleman-search/search-index-resource.rb add a new line around line 116:

store.each { |id, item| item[:url].sub!(/^/, ENV["ROOT_DOCPATH"].to_s) }

This prefixes every document url with the docpath, so that the search results render links that point to the right place to view the target document.

As long as ROOT_DOCPATH is unset when running middleman server, the local preview works fine. ROOT_DOCPATH just needs to be set when running middleman build.

It would be nicer if I could pass ROOT_DOCPATH from config/tech-docs.yml down to the relevant parts of both gems, but I couldn't figure out how to do that.

These changes are to two separate gems, which is why I haven't raised a PR - neither change makes sense without the other, and I'm not entirely happy about the hacky way this works, or adding a dependency on an environment variable.

I'm probably going to create a docker image that uses patched versions of the gems to allow us to do what we need to publish our documentation via github pages, but I hope you'll consider making these (or preferably less hacky) changes to allow publishing sites which are not hosted at the root docpath of the relevant domains.

I think the ability to use default github pages publishing makes it a lot easier for people to get their documentation sites up and running, and could lead to more teams being able to benefit from this gem - the search feature is a real game-changer.

[m-green]

Thank you for raising this with us @digitalronin. I'll pass this along to the team that's identifying possible fixes and improvements to the Tech Docs Template at the moment, as they should have GitHub Pages integration on their radar from your previous issue (https://github.com/alphagov/tdt-documentation/issues/67).

[digitalronin]

FYI, I created this template repository for teams who want to create github pages documentation sites using the tech-docs template:
https://github.com/ministryofjustice/template-documentation-site#template-documentation-site

[odlp]

We're using the tech-docs-gem for the API catalogue and also deploy to the default github pages URL for the moment.

I've opened a PR here which fixes the search issue: #196

There are 2-3 other asset-path related issues, relating to our use of Middleman's http_prefix setting (which avoids the need to use relative asset paths / links), which I'll be hoping to contribute fixes for in the coming days. Once resolved it should be cleaner to deploy to Github pages on a default URL.

[lfdebrux]

I think for this to work fully we also want a way to add the http prefix to the GOV.UK Frontend assets path: PR #292 should help with that.

[lfdebrux]

I think this functionality is also covered by issue #271. As issue #271 has the most recent updates, I'm going to close this issue in favour of that one.

[lfdebrux]

This issue may be fixed in release v3.2.0.

You can now configure your Tech Docs Template (TDT) to build your documentation site to use relative links to pages and assets.

Thanks @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).