Enable publishing via github pages, without requiring a dedicated domain name #191
Description
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.jsonwhen 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.erband 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.