Make docs portable by using relative URLs

[robons]

I'm testing out the use of the tech-docs for a project and I'm finding it difficult to use given the tool's expectations about where it's going to be placed on a server.

This issue is in the same vein as alphagov/tech-docs-template#213 and #196, however, I think it would be useful if the project could go a bit further than these suggestions.

It's often the case that people might want to host the same documentation in multiple places for ease of access, or even provide an offline version of said docs for users on air-gapped systems; for these reasons it's not always possible to know at build time exactly where the docs will end up being 'hosted'/stored. I don't believe the generated documentation should have these values baked into them. Ideally I'd like to be able to view and test the HTML docs on our continuous integration and know that the exact same files (without any URL changes) are deployed on 'production'.

I believe it would be much easier to make use of this template if the docs were built with zero knowledge of where they end up being deployed. This could be achieved by the use of relative URLs (think ./images/search-button.png or ../index.html in the case of folders) when including an image, linking to a page inside the same project or using the search functionality.

Unfortunately my team doesn't have the experience with ruby to make this a reality. Would it be possible for someone to implement this change?

[m-green]

Hi @robons - thanks for raising this with us.

Just to check my understanding - you'd like it so that when Middleman runs and builds the site, the generated files use relative urls throughout? Or is the issue something different?

(By the way, we may add your comment to the similar issues you mentioned, then close this issue - just to help us avoid having duplicating issues. Hope that's ok.)

[m-green]

Hi @robons - just checking if you saw my question above? ☝️

[robons]

Ah, sorry I missed that. Thanks for your reply.

Just to check my understanding - you'd like it so that when Middleman runs and builds the site, the generated files use relative urls throughout?

Yes, I think using relative URLs throughout would be helpful in that we can use it wherever it's stored without having to create a unique subdomain or run a local development server to view it.

(By the way, we may add your comment to the similar issues you mentioned, then close this issue - just to help us avoid having duplicating issues. Hope that's ok.)

I think this issue goes a bit beyond the other issues I've mentioned. I'd be happy for you to close this issue as long as it's clear what my suggested solution is on said issues.

[m-green]

Thank you @robons! I'll keep this issue open as we're hoping to work on this and the related issues soon.

[m-green]

@eddgrant has kindly put together a a reproduction case for the absolute links issue: https://github.com/hmrc/example-tech-docs-template-absolute-links

[eddgrant]

Hey folks,

I have been looking in to this a little, I thought it might be helpful to start building up a list of things which are affected by the use of relative paths. So far I have discovered that the following areas break when deploying a tech-docs site at a path other than /:

1. The Table of Contents (ToC) code.
2. The search functionality.

This is of course not an exhaustive list, just what I've noticed so far.

I have tried out an approach to alter the ToC generation code to inspect the :relative_links middleman directive and generate links using relative paths when configured to do so. This is working well in my local testing so far. The example code can be found here (please excuse my Ruby, it's not a language I know well). It's a pretty naive approach, which essentially entails figuring out how many path segments (e.g. "/" characters) the current page sits under and then creating a relative link which walks back up to the top of the site and then down to the target page.

I'm starting to look at the search functionality now, but I'm yet to figure out how this works. I initially thought it submitted a GET request to Google's search API however I'm starting to think that there's some JavaScript cleverness involved that I don't yet fully understand.

Hope that's of some use, I'm really keen to find a solution to this so if there's anything I can do to help please let me know.

[eddgrant]

Happy new year folks!

Further to my last comment I believe I now have everything working when generating sites using relative links. This includes the search functionality for which I took inspiration from @digitalronin notes in alphagov/tech-docs-template#213.

My changes are in the TRG-128 branch of our HMRC fork (diff against your master branch here).

I'm keen to avoid running a long-lived fork, would you be open to a discussion about getting my changes reviewed and merged back in to your repository? I'd be happy to talk through them and make a plan via some sort of video meetup (Meet/ Zoom etc).

Let me know your thoughts?

Cheers,

Edd

[lfdebrux]

Hi @eddgrant, sorry for the late reply, your changes look great!

I'm happy to review the changes in the usual way, are you happy to raise a pull request?

[eddgrant]

Hey @lfdebrux , no worries at all, thanks for getting back to me. Happy to raise a PR.

Since my last message I've found a couple of other areas which are also affected when generating sites using relative links:

1. /api/pages.json reports all the pages as being deployed at / , which breaks tech-docs-monitor's ability to generate links to the pages when it generates Slack alerts.
2. The JavaScript which expands, collapses and highlights the nav bar assumes the site is deployed at / and doesn't work for sites which use relative links.

I've added fixes for them both in our branch, would you like me to submit a single PR containing all the fixes, or do them in a more piecemeal style with multiple PRs? Let me know your preference and I'll get the necessary bits and bobs raised.

[lfdebrux]

Thanks!

A single PR would be great, if that's okay with you :)

[eddgrant]

Absolutely, will get one raised.

[eddgrant]

Here you go @lfdebrux #291

[lfdebrux]

Update on where we are this.

Thanks to a big effort from @eddgrant, we have some code in the main branch that should let you use the Middleman relative links feature. See PR #291 for the gory details, but the short version is that you just need to add the following lines to config.rb:

set :relative_links, true
activate :relative_assets

This covers the use case mentioned in this issue, and should also help with situations where a user is deploying to a service like GitHub Pages that has a prefix path.

If anyone feels like testing this out and reporting back on this issue, that would be amazing! We're hoping to turn this into a proper release soon.

[lfdebrux]

I have a PR to add some release notes for this change, in #293.

[lfdebrux]

This issue has been 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).