Search

Depending on the Bootstrap version used for your pkgdown website, search will be either built-in (Bootstrap 4 and next versions) or will need some more configuration of an external service (Bootstrap 3). We’d recomment switching to Bootstrap 4, see vignette("customization").

Bootstrap 4 and above: built-in search

Building your pkgdown website will build a search index, that will be used in the search form of the navbar using fuse.js.

You can exclude some paths from the search index. Below we exclude the changelog from the search index.

search:
  exclude: ['news/index.html']

Note that locally, search won’t work if you simply use pkgdown preview of the static files. You can use servr::httw("docs") instead.

Bootstrap 3: Algolia

pkgdown websites can integrate search capability using DocSearch from Algolia. DocSearch is a powerful search engine that is free for documentation websites. There are only two steps needed to enable DocSearch on a pkgdown website.

Indexing

Once you have published your pkgdown website, submit the pkgdown site URL to Docsearch. Docsearch will contact you via e-mail to confirm you are the website owner.

Docsearch will set up a crawler configuration that indexes your site every 24 hours. pkgdown builds a suggested Docsearch crawler configuration in docsearch.json and you should point the Docsearch team to this configuration as a starting point. If you want to optimize your search, Docsearch will accept pull requests to the configuration that incorporate additional options to fine tune the scraping.

Configuration

The Docsearch team will e-mail you some JavaScript to integrate into your website.

<script type="text/javascript">
  docsearch({ 
    apiKey: 'API_KEY',  // a long hex string
    indexName: 'INDEX_NAME', 
    inputSelector: '### REPLACE ME ####', 
    debug: false // Set debug to true if you want to inspect the dropdown 
}); 

Put the value of the apiKey and indexName parameters into your site _pkgdown.yml under template: params:

template:
  params:
    docsearch:
      api_key: API_KEY
      index_name: INDEX_NAME

You also need to add a url: field to _pkgdown.yml that specifies the location of your documentation on the web. For pkgdown, the URL field is:

url: https://pkgdown.r-lib.org

If you are building your own custom Docsearch index, you can also include your Docsearch app_id in _pkgdown.yml.

See the pkgdown configuration for a functional search configuration.

Once this configuration is complete, you should find a search bar after re-building your site. After search is enabled, pressing shift + / (i.e., “?”) will move the focus to the search bar.