- Enable search in configuration
- Hiding pages from search
- Generate search index when used as a gem
Just the Docs uses lunr.js to add a client-side search interface powered by a JSON index that Jekyll generates. All search results are shown in an auto-complete style interface (there is no search results page). By default, all generated HTML pages are indexed using the following data points:
- Page title
- Page content
- Page URL
In your site’s
_config.yml, enable search:
# Enable or disable the site search # Supports true (default) or false search_enabled: true
Pages are split into sections that can be searched individually. The sections are defined by the headings on the page. Each section is displayed in a separate search result.
# Split pages into sections that can be searched individually # Supports 1 - 6, default: 2 search.heading_level: 2
A search result can contain previews that show where the search words are found in the specific section.
# Maximum amount of previews per search result # Default: 3 search.previews: 3 # Maximum amount of words to display before a matched word in the preview # Default: 5 search.preview_words_before: 5 # Maximum amount of words to display after a matched word in the preview # Default: 10 search.preview_words_after: 10
The default is for hyphens to separate tokens in search terms:
gem-based is equivalent to
gem based, matching either word. To allow search for hyphenated words:
# Set the search token separator # Default: /[\s\-/]+/ # Example: enable support for hyphenated search words search.tokenizer_separator: /[\s/]+/
# Display the relative url in search results # Supports true (default) or false search.rel_url: false
The search button displays in the bottom right corner of the screen and triggers the search input when clicked.
# Enable or disable the search button that appears in the bottom right corner of every page # Supports true or false (default) search.button: true
Sometimes you might have a page that you don’t want to be indexed for the search nor to show up in search results, e.g, a 404 page. To exclude a page from search, add the
search_exclude: true parameter to the page’s YAML front matter:
--- layout: default title: Page not found nav_exclude: true search_exclude: true ---
If you use Just the Docs as a remote theme, you do not need the following steps.
If you use the theme as a gem, you must initialize the search by running this
rake command that comes with
$ bundle exec just-the-docs rake search:init
This command creates the
assets/js/zzzz-search-data.json file that Jekyll uses to create your search index. Alternatively, you can create the file manually with this content.