search

just-the-docs / just-the-docs

A modern, high customizable, responsive Jekyll theme for documentation with built-in search.
https://just-the-docs.com
MIT License
7.59k stars 3.68k forks source link

Search functionality is not working out of the box, zzzz-search-data.json is getting rendered as a HTML page instead of a JSON file #1466

Closed 5hwb closed 5 months ago

5hwb commented 6 months ago

Describe the bug

When creating a Jekyll site and adding on the just-the-docs theme later on, the search functionality does not work, generating no output. Further investigation revealed that the search data JSON file (assets/js/zzzz-search-data.json) was being treated by the template engine as a HTML page and applying the associated HTML markup and styling to the entire file, causing the JSON to become unparsable and preventing Lunr.js from successfully starting.

Opening up the browser dev tools reveals an error Uncaught SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data.

There is a simple workaround which involves setting the layout to none in the front matter of assets/js/zzzz-search-data.json, preventing the template engine from rendering the JSON as a HTML page. Open assets/js/zzzz-search-data.json and replace the front matter:

---
permalink: /assets/js/search-data.json
---

with the following:

---
layout: none
permalink: /assets/js/search-data.json
---

To Reproduce Steps to reproduce the behavior:

  1. Follow the Jekyll step-by-step tutorial to setup a Jekyll site
  2. In the site Gemfile, add the line gem "just-the-docs", "~> 0.8.2", the latest version as of 24 Apr 2024, then run bundle install
  3. Enable search as in the just-the-docs docs - set search_enabled = true in the project config at _config.yml
  4. Generate search index - bundle exec just-the-docs rake search:init
  5. Run the site locally - bundle exec jekyll serve
  6. Open the site and type anything in the search bar
  7. No results appear from the search.

Expected behavior Search results should appear when typing in the search bar.

Screenshots If applicable, add screenshots to help explain your problem.

Out of the box: Search functionality not working

image

What should happen: Search results show up after typing in search bar

image

Desktop (please complete the following information):

Additional context

Ruby version is 3.3.0 and was installed via the asdf version management tool.

mattxwang commented 6 months ago

Hi @5hwb, thank you for submitting an issue! I appreciate your in-depth steps to reproduce this problem - and it makes complete sense (we just fixed a similar issue in #1447). In particular, a concise reproduction pattern is:

  1. clone the template repository
  2. add the following to _config.yml:
defaults:
  - scope:
      path: ""
    values:
      layout: "default"

So, your suggested solution should resolve this problem; I will use layout: null (as explained in #1447). I'll submit a PR shortly. Thanks!

5hwb commented 6 months ago

No worries, glad to know it helped!