search

alphagov / tech-docs-template

A template for building technical documentation with a GOV.UK style
https://tdt-documentation.london.cloudapps.digital
MIT License
75 stars 36 forks source link

Search does not work for websites hosted below '/' (which includes all Github pages sites) #213

Closed digitalronin closed 2 years ago

digitalronin commented 5 years ago

Search does not work correctly unless the generated static site is served from the root of the web host. This makes it harder to use Github Pages to host techdocs documentation (it should be possible to get around this by setting up a DNS CNAME pointing to the documentation, but it would be nice not to have to do this).

What did you do? (steps to reproduce)

Given a techdocs documentation project, enable relative_assets by adding this line to config.rb

  activate :relative_assets

(Without this, links to CSS, JS & image files are all absolute links. See this thread for more details)

Generate the site, using the relative-links middleman command-line option

  bundle exec middleman build --relative-links

(Without relative-links, all links will be absolute, e.g. /page.html, which won't work)

Then, from the directory above build, serve the generated site

  python -m SimpleHTTPServer

Or however you want to serve the content. You can't just open build/index.html in your browser, because the XHR requests that the search function depends on will be blocked by the CORS policy.

Visit the URL in a browser

  http://localhost:8000/build

Now try to search for something.

What happened? (actual results)

Typing into the search box brings up a "Loading search index" panel, but no search results are displayed.

If you use debug tools to look at the javascript console, you can see a 404 error for /search.json

What should have happened? (expected results)

Search should work, even if the documentation is not located at the root of the web host.

Note: In the source of the govuk_tech_docs-1.6.3 gem, the file lib/assets/javascripts/_modules/search.js contains a hard-coded /search.json. If you replace this with search.json to make it a relative link then, when you regenerate the site, search seems to work, in that you see the results you expect, as you type into the search box. But, if you try to click on the resulting link to the page containing the search match, it's an absolute, rather than a relative link, so you get a 404 error.

lfdebrux commented 2 years ago

I think this functionality is covered by the issues tech-docs-gem issues #191 and #271. As issue #271 has the most recent updates, I'm going to close this issue in favour of that one.

lfdebrux commented 2 years ago

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