Skip to main content Link Search Menu Expand Document (external link)


Table of contents

  1. Enable search in configuration
    1. Search granularity
    2. Search previews
    3. Search tokenizer
    4. Display URL in search results
    5. Display search button
  2. Hiding pages from search
    1. Example
  3. 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

Enable search in configuration

In your site’s _config.yml, enable search:

# Enable or disable the site search
# Supports true (default) or false
search_enabled: true

Search granularity

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

Search previews

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

Search tokenizer

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 URL in search results

# Display the relative url in search results
# Supports true (default) or false
search.rel_url: false

Display search button

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

Generate search index when used as a gem

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 just-the-docs:

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