build_site2: Replacement versions of 'pkgdown::build_site()' etc. with...

In subugoe/muggle: Opinionated Devops for R Data Products Strictly Without Magic

Description

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

Usage

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 navbar will contain links to:

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

• The reference index.

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

• News (if present).

• An icon linking to the source repository.

You can override (and even remove) 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, remove some default components and add your own components.

navbar:
 structure:
   left:  [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:
   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
      aria-label: "twitter account"

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. When using icons with no text, for accessibility it's best practice to include an aria-label for screenreader users.

This yaml would override the default "articles" 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.

You can also customize the color scheme of the navbar by using the type and bg parameters:

navbar:
  type: dark
  bg: primary

will produce a navbar with a dark background of the primary color (defined by Bootstrap default, a Bootswatch theme, or bslib variable cf vignette("customization", package ="pkgdown"))

See Also

Other pkgdown functions: local_siteyaml(), override_pkgdownyaml()

subugoe/muggle documentation built on Nov. 26, 2021, 11:42 p.m.