Search

Docsy offers multiple options that let your readers search your site content, so you can pick one that suits your needs. You can choose from:

• Google Custom Search Engine (GCSE), the default option, which uses Google’s index of your public site to generate a search results page.
• Algolia DocSearch, which uses Algolia’s indexing and search mechanism. Search results are displayed as a pop-up. Algolia DocSearch is free for public documentation sites.
• Local search with Lunr, which uses Javascript to index and search your site without the need to connect to external services. This option doesn’t require your site to be public.

If you enable any of these search options in your project configuration file, a search box displays in the right of your top navigation bar. By default a search box also displays at the top of the section menu in the left navigation pane, which you can disable if you prefer, or if you’re using a search option that only works with the top search box.

Disabling the sidebar search box

By default, the search box appears in both the top navigation bar and at the top of the sidebar left navigation pane. If you don’t want the sidebar search box, set the site parameter sidebar_search_disable to true in hugo.toml/hugo.yaml/hugo.json:

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.ui]
sidebar_search_disable = true

params:
  ui:
    sidebar_search_disable: true

{
  "params": {
    "ui": {
      "sidebar_search_disable": true
    }
  }
}

Configure search with a Google Custom Search Engine

By default Docsy uses a Google Custom Search Engine (GCSE) to search your site. To enable this feature, you’ll first need to make sure that you have built and deployed a production version of your site, as otherwise your site won’t be crawled and indexed.

Setting up site search

1. Create a Google Custom Search Engine for your deployed site by clicking New search engine on the Custom Search page and following the instructions. Make a note of the ID for your new search engine.

2. Add any further configuration you want to your search engine using the Edit search engine options. In particular you may want to do the following:

   • Select Look and feel. Change from the default Overlay layout to Results only, as this option means your search results are embedded in your search page rather than appearing in a separate box. Click Save to save your changes.
   • Edit the default result link behavior so that search results from your site don’t open in a new tab. To do this, select Search Features - Advanced - Websearch Settings. In the Link Target field, type “_parent”. Click Save to save your changes.

Adding the search page

Once you have your search engine set up, you can add the feature to your site:

1. Ensure you have a Markdown file in content/en/search.md (and one per other languages if needed) to display your search results. It only needs a title and layout: search, as in the following example:

   • Front matter:
   • toml
   • yaml
   • json

   +++
   title = "Search Results"
   layout = "search"
   +++

   ---
   title: Search Results
   layout: search
   ---

   {
       "title": "Search Results",
       "layout": "search"
   }

2. Add your Google Custom Search Engine ID to the site params in hugo.toml/hugo.yaml/hugo.json. You can add different values per language if needed.

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params]
   # Google Custom Search Engine ID. Remove or comment out to disable search.
   gcs_engine_id = "011737558837375720776:fsdu1nryfng"

   params:
     gcs_engine_id: 011737558837375720776:fsdu1nryfng

   {
     "params": {
       "gcs_engine_id": "011737558837375720776:fsdu1nryfng"
     }
   }

Disabling GCSE search

If you don’t specify a Google Custom Search Engine ID for your project and haven’t enabled any other search options, the search box won’t appear in your site. If you’re using the default hugo.toml from the example site and want to disable search, just comment out or remove the relevant line.

Algolia DocSearch

As an alternative to GCSE, you can use Algolia DocSearch, which is free for public documentation sites. Docsy supports Algolia DocSearch v3.

Sign up for Algolia DocSearch

Complete the form at https://docsearch.algolia.com/apply. Proceed to the next step once you’ve received Algolia DocSearch parameters for your project.

Eager to test DocSearch?

Docsy defaults to the Algolia test-site parameters when none are provided. To enable search over the Algolia test, define params.search.algolia without any other fields, as outlined next.

Configure Algolia DocSearch

1. Ensure that GCSE search is disabled.

2. Add your project’s Algolia DocSearch parameters to hugo.toml/hugo.yaml/hugo.json, for example (using Algolia test values):

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params.search.algolia]
   appId = "R2IYF7ETH7"
   apiKey = "599cec31baffa4868cae4e79f180729b"
   indexName = "docsearch"

   params:
     search:
       algolia:
         appId: R2IYF7ETH7
         apiKey: 599cec31baffa4868cae4e79f180729b
         indexName: docsearch

   {
     "params": {
       "search": {
         "algolia": {
           "appId": "R2IYF7ETH7",
           "apiKey": "599cec31baffa4868cae4e79f180729b",
           "indexName": "docsearch"
         }
       }
     }
   }

To learn more about Algolia DocSearch V3, see Getting started.

When you’ve completed these steps, Algolia search should be enabled on your site. Search results are displayed as a pop-up, so you don’t need to add any search results page.

Customizing Algolia templates

You can customize or disable Docsy’s default Algolia support by creating the following template files:

• layouts/partials/algolia/head.html used by head.html to load Algolia DocSearch styles. It also issues a deprecation warning for params.algolia_docsearch.
• layouts/partials/algolia/scripts.html used by scripts.html to load and configure Algolia DocSearch.

Leave either file empty to disable Docsy’s implementation.

Local search with Lunr

Lunr is a Javascript-based search option that lets you index your site and make it searchable without the need for external, server-side search services. This is a good option particularly for smaller or non-public sites.

To add Lunr search to your Docsy site:

1. Enable local search in hugo.toml/hugo.yaml/hugo.json.

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params]
   offlineSearch = true

   params:
     offlineSearch: true

   {
     "params": {
       "offlineSearch": true
     }
   }

2. Remove or comment out any GCSE ID in hugo.toml/hugo.yaml/hugo.json and ensure Algolia DocSearch is set to false, as you can only have one type of search enabled. See Disabling GCSE search.

Once you’ve completed these steps, local search is enabled for your site and results appear in a drop down when you use the search box.

Changing the summary length of the local search results

You can customize the summary length by setting offlineSearchSummaryLength in hugo.toml/hugo.yaml/hugo.json.

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

#Enable offline search with Lunr.js
[params]
offlineSearch = true
offlineSearchSummaryLength = 200

params:
  offlineSearch: true
  offlineSearchSummaryLength: 200

{
  "params": {
    "offlineSearch": true,
    "offlineSearchSummaryLength": 200
  }
}

Changing the maximum result count of the local search

You can customize the maximum result count by setting offlineSearchMaxResults in hugo.toml/hugo.yaml/hugo.json.

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params]
offlineSearch = true
offlineSearchMaxResults = 25

params:
  offlineSearch: true
  offlineSearchMaxResults: 25

{
  "params": {
    "offlineSearch": true,
    "offlineSearchMaxResults": 25
  }
}

Changing the width of the local search results popover

The width of the search results popover will automatically widen according to the content.

If you want to limit the width, add the following scss into assets/scss/_variables_project.scss.

.td-offline-search-results {
  max-width: 460px;
}

Excluding pages from local search results

To exclude pages from local search results, add exclude_search: true to the the frontmatter of each page:

• Front matter:
• toml
• yaml
• json

+++
title = "Index"
weight = 10
exclude_search = true
+++

---
title: "Index"
weight: 10
exclude_search: true
---

{
  "title": "Index",
  "weight": 10,
  "exclude_search": true
}