Search: Support Github pages / http_prefix

[odlp]

Hello 👋 . I'm working on the API catalogue with the DSA team. We use the marvellous tech-docs-gem to build the site, which is then currently deployed to Github pages.

Context

For repo-specific Github pages, the site is deployed with the repo name prefixed in the path, e.g. https://alphagov.github.io/api-catalogue/. We'd like to use Middleman's http_prefix option to account for this path prefix, which will allow us to simplify and automate our build process.

Unfortunately with http_prefix configured the search doesn't work at the moment. Browsing /api-catalogue/index.html leads to a 404 Not found for /search.json (the asset is actually located at /api-catalogue/search.json).

Fix

Switches to use the search_index_path helper provided by the Middleman search gem itself, rather than hardcoding /search.json. This helper accounts for the http_prefix setting.

References:

• https://github.com/manastech/middleman-search#asset-pipeline
• https://github.com/manastech/middleman-search/blob/ed9e5254bb554988c755fc40238d9e9f67b20abe/lib/middleman-search/extension.rb#L29

[lfdebrux]

Hi @odlp, sorry it took so long for us to get back to you!

I'm reviewing these changes now so we can get them merged, they look great to me, only thing is that they need to be rebased. I can do this locally, but I'm unable to push to your pull request.

Are you happy to do the rebase?

Alternatively, you can give maintainers access to push changes, which might be easier for you!

[odlp]

Thanks @lfdebrux - PR rebased :)

[AntonyBishop]

Hi. This looks like this will fix an issue for us too. Any idea when this might be merged? Grateful for your assistance.

[lfdebrux]

@AntonyBishop thanks for the nudge, I've just merged this. However, I'm not sure when it will be released; there are some other pieces needed to complete support for http_prefix, specifically PR #292. If you want to have a look at that and leave some comments that would be appreciated!

[AntonyBishop]

Thanks @lfdebrux. Will take a look at the related release work.

[lfdebrux]

You might also have some luck with using the relative links settings instead of http_prefix, see issue #271 (comment).

[lfdebrux]

This change has been included in release v3.2.0.

I think there are some outstanding issues with http_prefix, however this release also includes support for relative links and assets.

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

Support for relative links and assets was introduced in pull request #291: Support sites deployed on paths other than "/" (by generating relative links).