search

alphagov / tech-docs-gem

Gem to distribute the tech docs project
https://tdt-documentation.london.cloudapps.digital/
MIT License
15 stars 38 forks source link

Search: Support Github pages / http_prefix #196

Closed odlp closed 2 years ago

odlp commented 4 years ago

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:

lfdebrux commented 2 years ago

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 commented 2 years ago

Thanks @lfdebrux - PR rebased :)

AntonyBishop commented 2 years ago

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

lfdebrux commented 2 years ago

@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 commented 2 years ago

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

lfdebrux commented 2 years ago

You might also have some luck with using the relative links settings instead of http_prefix, see issue https://github.com/alphagov/tech-docs-gem/issues/271#issuecomment-1042951634.

lfdebrux commented 2 years ago

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