In jayhesselberth/pkgdown-search: Make Static HTML Documentation for a Package

The goal of pkgdown is to make it easy for package developers to make elegant and useful packages websites. The defaults are tailored for smaller packages and for use on GitHub (particularly with new docs/ directory support), but it is flexible enough to be used as part of a bigger website. There are five parts to a pkgdown site:

Home page
Function reference
Articles
News
Navbar

To build a pkgdown site, run build_site(). The function has some arguments (mostly to control where the output), but most of the configuration options are controlled by _pkgdown.yaml. These options include:

The site title, if different from the package name.
A path to a set of template, if you want to override the default page templates provided by the site.
A bootswatch theme name to easily tweak the overall appearance of the site.

Other options control the appearance of the other parts of the site.

Home page

The home page will be automatically generated from one of the following four files:

index.Rmd
README.Rmd
index.md
README.md

pkgdown tries them in order, which means that if you want different display for GitHub and pkgdown, you can have both README.md and an index.md

When including big graphics in the README, you may find it easier to use knitr::include_graphics("foo.png") combined with chunk option out.width = '100%'. This will make the graphic scale with the size of the page.

Reference

The function reference generates one page for each .Rd file in man/, placing the results in reference/. This is mostly a straightforward translation of Rd to HTML, along with evaluating the examples, and auto-linking function names to their documentation.

pkgdown will also generate an overall index, which by default, is just an alphabetically ordered list of functions. However, the index is better with human curation because functions can be grouped by function and described en masse. To override the defaults, provide a reference key in _pkgdown.yml:

reference:
  - title: "Connecting to Spark"
    desc: >
      Functions for installing Spark components and managing
      connections to Spark
    contents: 
      - spark_config
      - spark_connect
      - spark_disconnect
      - spark_install
      - spark_log
  - title: "Reading and Writing Data"
    desc: "Functions for reading and writing Spark DataFrames."
    contents:
      - starts_with("spark_read")
      - starts_with("spark_write")
      - sdf-saveload

The reference should be an array of objects containing title, desc (description), and list of contents. Since common prefix and suffixes are often used for functional grouping, you can use the functions starts_with() and ends_with() to automatically include all functions with a common prefix or suffix. To match more complex patterns, use matches() with a regular expression.

The objects in reference can also contain a list of exclude, which allow you to exclude unwanted topics included via contents.

pkgdown will warn if you've forgotten to include any non-internal functions.

Articles

pkgdown will automatically build all .Rmd vignettes, including those in subdirectories. The only exception are .Rmd vignettes that start with '_'. This enables the use of child documents in bookdown. The output of the vignettes is rendered to articles/. pkgdown will ignore the output format defined in the yaml header, and always use html_fragment(toc = TRUE, toc_float = TRUE).

If you want to include an article on the website, but not in the package (e.g. because it's large), you can either place it in a subdirectory of vignettes/ or add to .Rbuildignore. As well, you must ensure that there is no vignettes: section in the article's yaml header. In the extreme case where you want to produce only articles but not vignettes, you should add the complete vignettes/ directory to .Rbuildignore and make sure that DESCRIPTION has no VignetteBuilder field.

As with the function reference, articles will also get a default index, and it can be customised in a similar way (referring to file names rather than function names):

articles:
  - title: "Extend shiny"
    desc: >
      These packages provide advanced features that can enhance your Shiny 
      apps.
    contents:
    - shinydashboard
    - shinythemes
    - shinyjs
    - htmlwidgets

News

If NEWS.md is present, it will be parsed into pieces broken up by second level headings. These will be rendered to news/, with one page per minor release (so that 2.2.0, 2.2.1, and 2.2.2 are all described on a single page).

If you want more detailed release notes (aimed at teaching people about the new features), you could put these in (e.g.) vignettes/news and customise the navbar.

Navbar {#navbar2}

By default, the navbar will show:

The home page, with a "home" icon.
"Get Started", if you have an article with the same name as the package.
Reference
Articles, if present.
News, if present.
A link to your your github repo (if listed in the DESCRIPTION url field).

You can override the defaults to:

Surface important articles directly from the navbar (a la http://spark.rstudio.com).
Provide deeper add additional hierarchical navigation (like
http://www.htmlwidgets.org).
Link to other, off-site, resources.

The navbar has a similar structure to the R Markdown website navbar. To customise, use the navbar field:

navbar:
  title: "sparklyr"
  type: inverse
  left:
    - text: "Home"
      href: index.html
    - text: "dplyr"
      href: articles/dplyr.html
    - text: "ML"
      href: articles/ML.html
    - text: "Extensions"
      href: articles/extensions.html
    - text: "Deployment"
      href: articles/deployment.html
    - text: "Reference"
      href: "reference/"
  right:
    - icon: fa-github
      href: https://github.com/rstudio/sparklyr

Search

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.

1. Ask Docsearch to index your site.

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

2. Add Docsearch parameters to your site configuration file.

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:

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

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

Finally, you 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: