Replacement versions of pkgdown::build_site() etc. with muggle defaults

Sets some muggle defaults for pkgdown to minimize code duplication across muggle projects. This includes overrides of _pkgdown.yml and _site.yml.

build_site2(run_dont_run = TRUE, override = list(), ...)

build_articles2(...)

build_article2(...)

Arguments

run_dont_run	Run examples that are surrounded in \dontrun?
override	An optional named list used to temporarily override values in _pkgdown.yml
...	Arguments passed on to pkgdown::build_site, pkgdown::build_articles, pkgdown::build_articles pkg Path to package. examples Run examples? seed Seed used to initialize so that random examples are reproducible. lazy If TRUE, will only rebuild articles and reference pages if the source is newer than the destination. preview If TRUE, or is.na(preview) && interactive(), will preview freshly generated section in browser. devel Use development or deployment process?If TRUE, uses lighter-weight process suitable for rapid iteration; it will run examples and vignettes in the current process, and will load code with pkgload::load_all().If FALSE, will first install the package to a temporary library, and will run all examples and vignettes in a new process.build_site() defaults to devel = FALSE so that you get high fidelity outputs when you building the complete site; build_reference(), build_home() and friends default to devel = TRUE so that you can rapidly iterate during development. new_process If TRUE, will run build_site() in a separate process. This enhances reproducibility by ensuring nothing that you have loaded in the current process affects the build process. install If TRUE, will install the package in a temporary library so it is available for vignettes. document Deprecated Use devel instead. quiet Set to FALSE to display output of knitr and pandoc. This is useful when debugging.

Related Functions and Methods

Functions

• build_articles2: build all articles

• build_article2: build an individual article

Additions to pkgdown

These replacement versions of pkgdown functions make the following changes to pkgdown, as applicable:

• If there are vignettes/, declaring a default vignette rendering function (local_siteyaml())

• Overriding some values in _pkgdown.yml by appending override_pkgdownyaml()) to override. Be careful not to provide conflicting overrides.

• Sets run_dont_run = TRUE, so that examples inside \dontrun{} are still run inside of pkgdown. Examples often need to be skipped on CRAN and other checks, though not when building pkgdown.

YAML config - navbar

By default, the top navigation bar (the "navbar") will contain links to:

• The home page, with a "home" icon.

• "Get Started", if you have an article with the same name as the package (e.g., vignettes/pkgdown.Rmd).

• Reference

• Articles (i.e., vignettes, if present).

• News (if present).

• A "github" icon with a link to your github repo (if listed in the DESCRIPTION url field).

You can override these defaults with the navbar field. It has two primary components: structure and components. These components interact in a somewhat complicated way, but the complexity allows you to make minor tweaks to part of the navbar while relying on pkgdown to automatically generate the rest.

The structure defines the layout of the navbar, i.e. the order of the components, and whether they're right aligned or left aligned. You can use this component to change the order of the default components, and to add your own components.

navbar:
  structure:
    left:  [home, intro, reference, articles, tutorials, news]
    right: [github]

The components describes the appearance of each element in the navbar. It uses the same syntax as RMarkdown. The following YAML snippet illustrates some of the most important features.

navbar:
  components:
    home: ~
    articles:
     text: Articles
     menu:
     - text: Category A
     - text: Title A1
       href: articles/a1.html
     - text: Title A2
       href: articles/a2.html
     - text: -------
     - text: "Category B"
     - text: Title B1
       menu:
       - text "Sub-category B11"
         href: articles/b11.html
     twitter:
       icon: "fab fa-twitter fa-lg"
       href: https://twitter.com/hadleywickham

Components can contain sub-menus with headings (indicated by missing href) and separators (indicated by a bunch of -). You can also use icons from fontawesome.

This yaml would override the default "articles" component, eliminate the "home" component, and add a new "twitter" component. Unless you explicitly mention new components in the structure they'll be added to the far right of the left menu.

See also

Other pkgdown functions: local_siteyaml(), override_pkgdownyaml()