build_articles: Build articles

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

Description

Each R Markdown vignette in vignettes/ and its subdirectories is rendered and saved to articles/. Vignettes are rendered using a special document format that reconciles rmarkdown::html_document() with your pkgdown template.

Usage

build_articles(pkg = ".", quiet = TRUE, lazy = TRUE, override = list(),
  preview = NA)

build_article(name, pkg = ".", data = list(), lazy = FALSE,
  quiet = TRUE)

Arguments

pkg	Path to package.
quiet	Set to FALSE to display output of knitr and pandoc. This is useful when debugging.
lazy	If TRUE, will only re-build article if input file has been modified more recently than the output file.
override	An optional named list used to temporarily override values in _pkgdown.yml
preview	If TRUE, or is.na(preview) && interactive(), will preview freshly generated section in browser.
name	Name of article to render. This should be either a path relative to vignettes/ without extension, or index or README.
data	Additional data to pass on to template.

External files

pkgdown differs from base R in its handling of external files. When building vignettes, R assumes that vignettes are self-contained (a reasonable assumption when most vignettes were PDFs) and only copies files explicitly listed in .install_extras. pkgdown takes a different approach based on rmarkdown::find_external_resources, and it will also copy any images that you link to. If for some reason the automatic detection doesn't work, you will need to add a resource_files field to the yaml metadata, .e.g

---
title: My Document
resource_files:
 - data/mydata.csv
 - images/figure.png
---

Note that you can not use the fig.path to change the output directory of generated figures as the default is a strong assumption of rmarkdown.

YAML config

To tweak the index page, you need a section called articles, which provides a list of sections containing, a title, list of contents, and optional description.

For example, this imaginary file describes some of the structure of the R markdown articles:

articles:
- title: R Markdown
  contents:
  - starts_with("authoring")
- title: Websites
  contents:
  - rmarkdown_websites
  - rmarkdown_site_generators

Note that contents can contain either a list of vignette names (including subdirectories), or if the functions in a section share a common prefix or suffix, you can use starts_with("prefix") and ends_with("suffix") to select them all. If you don't care about position within the string, use contains("word"). For more complex naming schemes you can use an aribrary regular expression with matches("regexp").

pkgdown will check that all vignettes are included in the index this page, and will generate a warning if you have missed any.

YAML header

By default, pkgdown builds all articles with rmarkdown::html_document() using setting the template parameter to a custom built template that matches the site template. You can override this with a pkgdown field in your yaml metadata:

pkgdown:
  as_is: true

This will tell pkgdown to use the output_format that you have specified. This format must accept template, theme, and self_contained in order to work with pkgdown.

If the output format produces a PDF, you'll also need to specify the extension field:

pkgdown:
  as_is: true
  extension: pdf

Supressing vignettes

If you want articles that are not vignettes, either put them in subdirectories or list in .Rbuildignore. An articles link will be automatically added to the default navbar if the vignettes directory is present: if you do not want this, you will need to customise the navbar. See build_site() details.

Figures

You can control the default rendering of figues by specifying the figures field in _pkgdown.yml. The default settings are equivalent to:

figures:
  dev: grDevices::png
  dpi: 96
  dev.args: []
  fig.ext: png
  fig.width: 7.2916667
  fig.height: ~
  fig.retina: 2
  fig.asp: 1.618

jayhesselberth/pkgdown-search documentation built on May 17, 2019, 9:12 a.m.