Assets: Support Github pages / http_prefix

odlp commented 3 years ago

Hello 👋

This PR fixes asset URLs for sites built for Github pages using the default URL (like the API catalogue), in which paths are prefixed with the repo name.

Changes

Allow $govuk-assets-path to be overriden by implementors
Use Sprockets URL helpers to ensure image backround URLs in CSS account for Middleman's http_prefix setting

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.

Our Middleman config looks like this:

# Without prefix for 'middleman serve'
set(:govuk_assets_path, "/assets/govuk/assets/")

# Add '/api-catalogue/' for 'middleman build', for Github Pages compatibility
configure :build do
  set(:build_dir, "build/api-catalogue")
  set(:http_prefix, "/api-catalogue/")
  set(:govuk_assets_path, "/api-catalogue/assets/govuk/assets/")
end

With this PR all asset URLs correctly include the /api-catalogue/ prefix, and we can avoid using Middleman's activate :relative_assets feature.

References

middleman-sprockets asset_path / image-url helpers
GOV.UK Frontend using !default to allow overrides
Semi-related PR which fixes search with http_prefix configued

m-green commented 2 years ago

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

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

alphagov / tech-docs-gem