Package 'albersdown'

Title: Minimalist Theme and Vignette Kit for 'pkgdown' and R Markdown
Description: Provides a minimalist 'ggplot2' theme, colour scales, and 'pkgdown' template built around a curated colour palette system inspired by Josef Albers' colour theory (Albers (1963, ISBN:978-0-300-17935-4) "Interaction of Color"). Includes helpers to apply consistent theming to 'ggplot2' plots, 'gt' tables, and 'bslib' Bootstrap 5 sites, along with one-command setup functions for adopting the style across an R package.
Authors: Bradley R. Buchsbaum [aut, cre]
Maintainer: Bradley R. Buchsbaum <[email protected]>
License: MIT + file LICENSE
Version: 2.1.0.9000
Built: 2026-10-04 00:51:47 UTC
Source: https://github.com/bbuchsbaum/albersdown

Help Index

bs_theme for pkgdown (light/dark aware)

Description

Convenience wrapper exposing core variables; most consumers won't need this directly if they use template: { package: albersdown }.

Usage

albers_bs_theme(
  family = "red",
  preset = c("homage", "interaction", "study", "structural", "adobe", "midnight"),
  accent = NULL,
  bg = NULL,
  fg = NULL
)

Arguments

family

Palette family name (default "red").
preset

Visual preset (default "homage"). See albers_presets().
accent

Primary accent color (default A700 of the chosen family).
bg

Background color (default derived from preset).
fg

Foreground/text color (default derived from preset).

Value

A bslib::bs_theme object.

Examples

if (requireNamespace("bslib", quietly = TRUE)) {
  albers_bs_theme()
}

Discrete colours for a family

Description

The "contrast" set leads with the family's own tone and its interaction complement – the two colours of the title plate (red and gold for the red family) – then the complementary family (blue), the family at another lightness, the complementary family at another lightness, and a warm neutral. With mode = "dark" each slot keeps its hue (only its lightness changes), so a category keeps its colour when the page switches theme. Adjacent levels differ in hue, so a two-group comparison is always legible. The "family" set is the single-hue A900-A300 ramp.

Usage

albers_discrete(
  family = getOption("albersdown.family", "red"),
  type = c("contrast", "family"),
  mode = c("light", "dark")
)

Arguments

family

Palette family.
type

"contrast" (default) or "family".
mode

"light" (default) or "dark": lighter tones that hold up on the night ground (used for the dark twins of figures).

Value

Character vector of hex colours.

Examples

albers_discrete("red")
albers_discrete("teal", type = "family")

Return four-tone Homage family by name

Description

Return four-tone Homage family by name

Usage

albers_palette(family = c("red", "lapis", "ochre", "teal", "green", "violet"))

Arguments

family

One of "red", "lapis", "ochre", "teal".

Value

Named character vector of four hex colors (A900, A700, A500, A300).

Examples

albers_palette("red")
albers_palette("lapis")

Image-derived Homage palettes (A900 -> A300)

Description

Four-tone families distilled from the uploaded grid; order is darkest to lightest (A900, A700, A500, A300).

Usage

albers_palette_img(family = c("red", "lapis", "ochre", "teal", "green"))

Arguments

family

One of "red","lapis","ochre","teal","green"

Value

Named character vector of four hex colors (A900, A700, A500, A300).

Examples

albers_palette_img("red")

List available Albers directions

Description

Returns the two 2.0 directions: "homage" (warm cream ground, serif body, light code) and "interaction" (cool grey ground, grotesk, dark code). The legacy presets "study", "structural", "adobe", and "midnight" are still accepted by theme_albers() for backward compatibility but are no longer featured.

Usage

albers_presets()

Value

Character vector of direction names.

Examples

albers_presets()

Interpolate n colors along a palette family gradient

Description

Uses colorRampPalette to interpolate between the four tones of a family (A900 → A300), producing an arbitrary number of evenly spaced colors.

Usage

albers_ramp(family = "red", n = 9, reverse = FALSE)

Arguments

family

Palette family name.
n

Number of colors to return.
reverse

If TRUE, return colors from light to dark.

Value

Character vector of n hex colors.

Examples

albers_ramp("lapis", n = 5)

Register the bundled Albers display fonts for R graphics

Description

albersdown ships static TTF builds of Familjen Grotesk (the Homage display face) and Space Grotesk (the Interaction display face) so that ggplot2 plots can use the same typefaces as the rendered HTML pages. Call this once per session – for example in a vignette setup chunk – before theme_albers(). Once the fonts are registered, theme_albers() picks the direction's display font automatically (Homage -> Familjen Grotesk, Interaction -> Space Grotesk).

Usage

albers_register_fonts()

Details

Requires the systemfonts package and a font-aware graphics device such as ragg (e.g. knitr::opts_chunk$set(dev = "ragg_png")). Without those, plots fall back to the system "sans" family, so package examples and CRAN checks never depend on the bundled fonts.

Value

Invisibly, a character vector of the font families that were registered (empty if systemfonts is unavailable or the files are missing).

Examples

# Registers the bundled display fonts for the current session. Plot with a
# font-aware device (e.g. ragg); the default pdf/postscript device cannot
# render registered fonts. Wrapped in \dontrun because it mutates the
# session-wide font registry.
## Not run: 
albers_register_fonts()

## End(Not run)

Visual swatch of Albers palette families and presets

Description

Draws a tile plot showing the four tones of each palette family, optionally faceted by preset ground colors. Useful for quickly previewing the design system in a notebook or presentation.

Usage

albers_swatch(
  families = c("red", "lapis", "ochre", "teal", "green", "violet"),
  show_presets = FALSE
)

Arguments

families

Character vector of families to show. Defaults to all six.
show_presets

If TRUE, add a row of preset ground colors below the palette tones. Defaults to FALSE.

Value

A ggplot object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  albers_swatch()
}

Albers vignette output format

Description

A drop-in replacement for rmarkdown::html_vignette() that applies the albersdown theme with no files to copy into ⁠vignettes/⁠. The stylesheet, the fonts for the chosen direction, and the page script are taken from the installed package and embedded in the self-contained HTML, so the result is CRAN-safe (no network requests).

Usage

albers_vignette(
  family = "red",
  preset = "homage",
  style = c("minimal", "balanced", "assertive"),
  toc = TRUE,
  toc_depth = 3,
  fig_width = 6.6,
  fig_height = 4.1,
  plot_theme = TRUE,
  dark_figures = TRUE,
  phone_figures = TRUE,
  math_method = "mathml",
  fonts = c("direction", "both"),
  css = NULL,
  includes = NULL,
  ...
)

Arguments

family

Accent family: one of "red", "lapis", "ochre", "teal", "green", "violet". While the vignette renders, the albersdown.family and albersdown.preset options are set, so scale_color_albers(), scale_fill_albers() and theme_albers() follow it without repeating the family.
preset

Direction: "homage" (warm, serif body) or "interaction" (cool, grotesk, dark code). Legacy presets are accepted.
style

Weight of the structural marks: "minimal" (default), "balanced" or "assertive".
toc, toc_depth

Table of contents, passed to rmarkdown::html_vignette().
fig_width, fig_height

Default figure size in inches.
plot_theme

If TRUE, set theme_albers() (matching family and preset) as the ggplot2 theme while the vignette renders.
dark_figures

If TRUE (and plot_theme is on), each auto-printed ggplot is also rendered with theme_albers(mode = "dark"); the page shows that version in dark mode instead of a light plot on a dark page. This adds one image per plot to the HTML. Plots in chunks with fig.show = "hold", "animate" or "hide" get no dark version and stay light in dark mode.
phone_figures

If TRUE, each plot (ggplot2, grid or base graphics) is also drawn at phone width (3.6 in, the same aspect ratio), so its text is legible in a phone's column; the page shows that drawing while the figure is displayed narrower than about 470 CSS px, in light and dark mode alike (the dark version is drawn when dark_figures is on). Printing and the enlarged view use the full figure. Figures narrower than 4.5 in, figures whose out.width is not a percentage, animations and non-PNG devices are left as they are.
math_method

How equations are rendered. The default "mathml" has pandoc write native MathML, which browsers display without any download, so vignettes with math stay offline. Use "mathjax" (fetched from a CDN when the page is read) for heavier TeX.
fonts

Which bundled typefaces to embed: "direction" (default) embeds only the chosen direction's faces; "both" embeds homage's and interaction's, for a page that previews both (about 130 KB more).
css

Additional stylesheets, applied after the theme.
includes

Additional rmarkdown::includes(); combined with the theme's own head and body includes.
...

Further arguments passed to rmarkdown::html_vignette().

Details

Use it in a vignette's YAML header: 

output:
  albersdown::albers_vignette:
    family: teal
    preset: interaction

The format sets the page's family and direction before any content is drawn (no restyle on load), sets knitr defaults suited to the theme (collapse = TRUE, comment = "#>", retina figures at full column width, the ragg device when available), and, when plot_theme = TRUE and ggplot2 is installed, sets theme_albers() as the ggplot2 theme for the duration of the render.

albers_vignette() is new in albersdown 2.1.0. A package whose vignettes use it should declare ⁠albersdown (>= 2.1.0)⁠ in Suggests (as use_albersdown() writes). If building a vignette fails with ⁠'albers_vignette' is not an exported object from 'namespace:albersdown'⁠, the albersdown installed is 2.0.0 or older: update it.

Value

An R Markdown output format.

Examples

## Not run: 
rmarkdown::render("my-vignette.Rmd",
  output_format = albersdown::albers_vignette(family = "teal"))

## End(Not run)

Quiet, legible gt style with subtle stripe from A300

Description

Quiet, legible gt style with subtle stripe from A300

Usage

gt_albers(
  x,
  family = "red",
  preset = c("homage", "interaction", "study", "structural", "adobe", "midnight"),
  base_size = 14,
  width = 720,
  bg = NULL,
  fg = NULL
)

Arguments

x

A gt table
family

Palette family for subtle accents
preset

Visual preset (default "homage"). See albers_presets().
base_size

Base font size in pixels (default 14).
width

Table width in pixels (default 720). Use NULL for auto.
bg

Override background color (default derived from preset).
fg

Override text color (default derived from preset).

Value

A styled gt table object.

Examples

if (requireNamespace("gt", quietly = TRUE)) {
  tbl <- gt::gt(head(mtcars))
  gt_albers(tbl)
}

One-command migration to latest albersdown

Description

Convenience helper for existing packages that already use the vendored albersdown setup (copied albers.css/albers.js in ⁠vignettes/⁠) and need to refresh it with the latest assets while choosing an Albers accent family and preset. To move to the output format instead, use use_albersdown(path, method = "format").

Usage

migrate_albersdown(
  path,
  family = "red",
  preset = c("homage", "interaction", "study", "structural", "adobe", "midnight"),
  dry_run = FALSE
)

Arguments

path

Path to the package directory. Must be supplied explicitly; there is no default so that the function never writes to an unexpected location.
family, preset

As in use_albersdown(): if not given, the package's current family and direction are kept.
dry_run

if TRUE, report changes without writing files.

Value

TRUE invisibly.

Examples

if (interactive()) {
  migrate_albersdown(path = ".", family = "teal", preset = "midnight", dry_run = TRUE)
}

Scales that use the family's tones (discrete/continuous)

Description

Discrete scales use albers_discrete(): by default the family's tone is paired with its Albers complement and ochre so adjacent groups stay distinguishable. Use type = "family" for the single-hue ramp. Continuous scales run from a light tint to the family's A900.

Usage

scale_color_albers(
  family = getOption("albersdown.family", "red"),
  discrete = TRUE,
  type = c("contrast", "family"),
  ...
)

scale_fill_albers(
  family = getOption("albersdown.family", "red"),
  discrete = TRUE,
  type = c("contrast", "family"),
  ...
)

Arguments

family

Palette family. Defaults to the albersdown.family option (set by albers_vignette() while a vignette renders), else "red".
discrete

Whether to use a discrete palette; if FALSE, uses a gradient.
type

Discrete colour set, "contrast" (default) or "family"; see albers_discrete().
...

Passed to underlying ggplot2 scale.

Value

A ggplot2 scale object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  ggplot2::ggplot(iris, ggplot2::aes(Sepal.Length, Sepal.Width,
    color = Species)) + ggplot2::geom_point() + scale_color_albers()
}

Distinct, colorblind-friendly line palette across families

Description

Uses one high-contrast tone (default A700) from different families to maximize separation between lines. This departs from the single-family aesthetic but improves readability for multi-series lines.

Usage

scale_color_albers_distinct(n = NULL, tone = c("A700", "A900", "A500"), ...)

Arguments

n

Number of colors needed; defaults to length of available families (6).
tone

One of "A700", "A900", or "A500".
...

Passed to ggplot2::scale_color_manual().

Value

A ggplot2 scale object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  df <- data.frame(x = 1:6, y = 1:6, g = paste0("G", 1:6))
  ggplot2::ggplot(df, ggplot2::aes(x, y, color = g)) +
    ggplot2::geom_point() + scale_color_albers_distinct()
}

Diverging color scale (continuous)

Description

Diverging color scale (continuous)

Usage

scale_color_albers_diverging(
  low_family = "red",
  high_family = albers_complement(low_family),
  midpoint = 0,
  neutral = "#e5e7eb",
  ...
)

Arguments

low_family, high_family

Homage families for the two sides
midpoint

numeric midpoint for the diverging scale (default 0)
neutral

hex color for the midpoint (default matches CSS border)
...

passed to ggplot2::scale_color_gradient2()

Value

A ggplot2 scale object.

Diverging color scale with multiple stops (continuous)

Description

Uses a 5-stop palette (low2, low1, neutral, high1, high2) for smoother transitions around the midpoint.

Usage

scale_color_albers_diverging_n(
  low_family = "red",
  high_family = albers_complement(low_family),
  neutral = "#e5e7eb",
  ...
)

Arguments

low_family, high_family

Homage families for the two sides
neutral

hex color for the midpoint (default matches CSS border)
...

passed to ggplot2::scale_color_gradient2()

Value

A ggplot2 scale object.

Convenience scale: highlight vs other (color)

Description

Returns a manual color scale mapping a single highlighted group to a family tone (default A700) and all other points to a neutral gray.

Usage

scale_color_albers_highlight(
  family = "red",
  tone = c("A700", "A900", "A500", "A300"),
  other = "#9aa0a6",
  highlight = "highlight",
  other_name = "other",
  ...
)

Arguments

family

Palette family name.
tone

One of A900, A700, A500, A300 used for the highlight color.
other

Hex color used for non-highlight values.
highlight

Name of the value that should receive the highlight color.
other_name

Name of the value that should receive the neutral color.
...

Passed to ggplot2::scale_color_manual().

Value

A ggplot2 scale object.

Image-derived sequential color scale

Description

Image-derived sequential color scale

Usage

scale_color_albers_img(family = "red", discrete = TRUE, ...)

scale_fill_albers_img(family = "red", discrete = TRUE, ...)

Arguments

family

One of "red","lapis","ochre","teal","green"
discrete

Whether to use discrete palette; if FALSE uses a gradient.
...

Passed to underlying ggplot2 scale.

Value

A ggplot2 scale object.

Image-derived diverging color scale (gradientn)

Description

Image-derived diverging color scale (gradientn)

Usage

scale_color_albers_img_diverging(
  low_family,
  high_family,
  neutral = "#E4E0D9",
  ...
)

Arguments

low_family

Family for the low side (left)
high_family

Family for the high side (right)
neutral

Hex color for the midpoint (default derived from image)
...

Passed to ggplot2::scale_color_gradientn

Value

A ggplot2 scale object.

Pre-canned image-derived diverging pairs

Description

Pre-canned image-derived diverging pairs

Usage

scale_color_albers_img_red_teal(neutral = "#E4E0D9", ...)

scale_color_albers_img_lapis_ochre(neutral = "#E4E0D9", ...)

scale_color_albers_img_green_red(neutral = "#E4E0D9", ...)

scale_fill_albers_img_red_teal(neutral = "#E4E0D9", ...)

scale_fill_albers_img_lapis_ochre(neutral = "#E4E0D9", ...)

scale_fill_albers_img_green_red(neutral = "#E4E0D9", ...)

Arguments

neutral

Midpoint color (default from image); use "#e5e7eb" to match site CSS
...

Passed to the underlying gradientn scale

Value

A ggplot2 scale object.

Distinct, colorblind-friendly fill palette across families

Description

Uses one high-contrast tone (default A700) from different families to maximize separation between filled regions. Fill counterpart of scale_color_albers_distinct.

Usage

scale_fill_albers_distinct(n = NULL, tone = c("A700", "A900", "A500"), ...)

Arguments

n

Number of colors needed; defaults to length of available families (6).
tone

One of "A700", "A900", or "A500".
...

Passed to ggplot2::scale_fill_manual().

Value

A ggplot2 scale object.

Diverging fill scale (continuous)

Description

Diverging fill scale (continuous)

Usage

scale_fill_albers_diverging(
  low_family = "red",
  high_family = albers_complement(low_family),
  midpoint = 0,
  neutral = "#e5e7eb",
  ...
)

Arguments

low_family, high_family

Homage families for the two sides
midpoint

numeric midpoint for the diverging scale (default 0)
neutral

hex color for the midpoint (default matches CSS border)
...

passed to ggplot2::scale_color_gradient2()

Value

A ggplot2 scale object.

5-class diverging (discrete)

Description

Useful for binned choropleths or sliced residuals. The middle class uses the neutral color.

Usage

scale_fill_albers_diverging_5(
  low_family = "red",
  high_family = albers_complement(low_family),
  neutral = "#e5e7eb",
  labels = ggplot2::waiver(),
  ...
)

scale_color_albers_diverging_5(
  low_family = "red",
  high_family = albers_complement(low_family),
  neutral = "#e5e7eb",
  labels = ggplot2::waiver(),
  ...
)

Arguments

low_family, high_family

Homage families for the two sides
neutral

hex color for the midpoint (default matches CSS border)
labels

Optional labels for the five classes (low2, low1, mid, high1, high2)
...

Passed to ggplot2::scale_fill_manual() or ggplot2::scale_color_manual().

Value

A ggplot2 scale object.

Diverging fill scale with multiple stops (continuous)

Description

Diverging fill scale with multiple stops (continuous)

Usage

scale_fill_albers_diverging_n(
  low_family = "red",
  high_family = albers_complement(low_family),
  neutral = "#e5e7eb",
  ...
)

Arguments

low_family, high_family

Homage families for the two sides
neutral

hex color for the midpoint (default matches CSS border)
...

passed to ggplot2::scale_color_gradient2()

Value

A ggplot2 scale object.

Convenience scale: highlight vs other (fill)

Description

Convenience scale: highlight vs other (fill)

Usage

scale_fill_albers_highlight(
  family = "red",
  tone = c("A700", "A900", "A500", "A300"),
  other = "#9aa0a6",
  highlight = "highlight",
  other_name = "other",
  ...
)

Arguments

family

Palette family name.
tone

One of A900, A700, A500, A300 used for the highlight color.
other

Hex color used for non-highlight values.
highlight

Name of the value that should receive the highlight color.
other_name

Name of the value that should receive the neutral color.
...

Passed to ggplot2::scale_color_manual().

Value

A ggplot2 scale object.

Image-derived diverging fill scale (gradientn)

Description

Image-derived diverging fill scale (gradientn)

Usage

scale_fill_albers_img_diverging(
  low_family,
  high_family,
  neutral = "#E4E0D9",
  ...
)

Arguments

low_family

Family for the low side (left)
high_family

Family for the high side (right)
neutral

Hex color for the midpoint (default derived from image)
...

Passed to ggplot2::scale_fill_gradientn

Value

A ggplot2 scale object.

Discrete linetype scale to pair with Albers colors

Description

Provides a sensible set of linetypes for multi-series line charts.

Usage

scale_linetype_albers(...)

Arguments

...

Passed to ggplot2::scale_linetype_manual().

Value

A ggplot2 scale object.

Minimal, legible plot theme inspired by Josef Albers

Description

Minimal, legible plot theme inspired by Josef Albers

Usage

theme_albers(
  family = getOption("albersdown.family", "red"),
  preset = getOption("albersdown.preset", c("homage", "interaction", "study",
    "structural", "adobe", "midnight")),
  base_size = 13,
  base_family = NULL,
  bg = NULL,
  fg = NULL,
  grid_color = NULL,
  mode = c("light", "dark")
)

Arguments

family

Palette family used by companion scales.
preset

Visual direction: "homage" (warm cream ground) or "interaction" (cool grey ground). Legacy presets "study", "structural", "adobe", and "midnight" are still accepted for backward compatibility.
base_size

Base font size.
base_family

Base font family. Plots fall back to the system "sans" stack; install the matching typefaces (Familjen Grotesk / Space Grotesk, etc.) and pass e.g. base_family = "Familjen Grotesk" for full fidelity.
bg

Override background color. Defaults to the preset's surface (the vignette sheet), so figures sit on the page rather than in a box.
fg

Override foreground/text color (default derived from preset).
grid_color

Override grid line color (default derived from preset).
mode

"light" (default) or "dark": the direction's night ground and ink, matching the page's dark mode. albers_vignette() uses it to render a dark twin of each plot.

Value

A ggplot2 theme object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) +
    ggplot2::geom_point() + theme_albers()
}

Stripped theme for maps, brain surfaces, and abstract compositions

Description

Extends theme_albers by removing axes, grid lines, ticks, and panel border – leaving only the plot background, titles, and legend. Useful for spatial visualizations where coordinate axes are meaningless.

Usage

theme_albers_void(
  family = "red",
  preset = c("homage", "interaction", "study", "structural", "adobe", "midnight"),
  base_size = 13,
  base_family = NULL,
  bg = NULL,
  fg = NULL
)

Arguments

family

Palette family used by companion scales.
preset

Visual direction: "homage" (warm cream ground) or "interaction" (cool grey ground). Legacy presets "study", "structural", "adobe", and "midnight" are still accepted for backward compatibility.
base_size

Base font size.
base_family

Base font family. Plots fall back to the system "sans" stack; install the matching typefaces (Familjen Grotesk / Space Grotesk, etc.) and pass e.g. base_family = "Familjen Grotesk" for full fidelity.
bg

Override background color. Defaults to the preset's surface (the vignette sheet), so figures sit on the page rather than in a box.
fg

Override foreground/text color (default derived from preset).

Value

A ggplot2 theme object.

Configure current package to use albersdown (back-compat wrapper)

Description

This wrapper preserves the old name and forwards to use_albersdown().

Usage

use_albers_vignettes(path = ".", ...)

Arguments

path

Path to the package directory. Defaults to the current working directory to preserve the original wrapper behavior.
...

Additional arguments passed to use_albersdown().

Value

TRUE invisibly.

Examples

if (interactive()) {
  use_albers_vignettes()
}

One-shot setup for existing packages

Description

Adopt the albersdown theme in an existing package.

Usage

use_albersdown(
  path,
  family = "red",
  preset = c("homage", "interaction", "study", "structural", "adobe", "midnight"),
  apply_to = c("all", "new"),
  dry_run = FALSE,
  fallback_extra = c("auto", "always", "never"),
  force_replace = TRUE,
  method = c("format", "vendor"),
  readme = FALSE
)

Arguments

path

Path to the package directory. Must be supplied explicitly; there is no default so that the function never writes to an unexpected location.
family

One of "red", "lapis", "ochre", "teal", "green", "violet" (case-insensitive). If not given, the family the package already uses is kept: from its vignettes (a ⁠family:⁠ stated in their albers_vignette() entries, or albersdown 2.0's params; the most common if they differ), else from site defaults in pkgdown/extra.js or ⁠_pkgdown.yml⁠, else "red". With apply_to = "new" the site defaults come first. A message says which was kept and where it came from.
preset

Direction, "homage" or "interaction" (legacy presets are accepted; case-insensitive). If not given, inferred like family, else "homage". See albers_presets().
apply_to

"all" to convert the vignettes as well (every ⁠*.Rmd⁠ in ⁠vignettes/⁠; with method = "vendor" also ⁠*.qmd⁠), or "new" to set up only ⁠_pkgdown.yml⁠, the site defaults and DESCRIPTION (vignette dependencies only if a vignette is already on the format).
dry_run

if TRUE, report the changes (including .Rbuildignore and .gitignore entries) without writing anything.
fallback_extra

method = "vendor" only. Controls writing site-wide fallbacks into ⁠pkgdown/⁠:

  • "auto": write pkgdown/extra.css and pkgdown/extra.js whenever site-wide defaults are needed.

  • "always": always write to ⁠pkgdown/⁠ (useful as a safety net or for custom setups).

  • "never": never copy site-wide fallbacks.

With method = "format", only the site default family is written, to pkgdown/extra.js, and only when it is not red/homage (or was set before).
force_replace

method = "vendor" only. If TRUE (default), overwrite existing albersdown assets and replace existing vignette CSS/header hooks so albersdown becomes the active theme.
method

"format" (default) or "vendor"; see Details.
readme

If TRUE, add a short note about the theme to README.Rmd (re-knit it afterwards) or, when there is none, README.md (default FALSE), describing the setup method makes.

Details

With method = "format" (the default) each ⁠vignettes/*.Rmd⁠ whose first output format is html_vignette is switched to albers_vignette(), and ⁠_pkgdown.yml⁠ is pointed at the albersdown template (it is created, and added to .Rbuildignore with ⁠docs/⁠, if missing). DESCRIPTION gains bbuchsbaum/albersdown in Config/Needs/website. When at least one vignette is on the format, it also gains ⁠albersdown (>= <installed version>)⁠ in Suggests (or that bound where albersdown is already in Imports/Depends), knitr and rmarkdown, and VignetteBuilder: knitr; and, when the installed albersdown is a development version (not on CRAN), Remotes: bbuchsbaum/albersdown, so that R CMD check and CI install the version with albers_vignette() (⁠R CMD check --as-cran⁠ notes that field). Otherwise (no vignettes, none convertible, or apply_to = "new" with none already on the format) the adoption is site-only and no field that R CMD check reads is changed. Nothing is copied into ⁠vignettes/⁠. Edits are textual (other output formats, comments, key order and line endings are kept) and each changed file is backed up to ⁠.albersdown.bak/⁠, which is added to .Rbuildignore and .gitignore.

A package set up by albersdown 2.0 (the vendor setup) is migrated: the setup-chunk lines and params (family, preset) that 2.0 added are removed, as are its generated pkgdown/extra.css (an ⁠@import⁠ of the theme) and pkgdown/extra.js, and its README note is rewritten. The copied albers.css, albers.js, albers-header.html and fonts in ⁠vignettes/⁠ are moved to ⁠.albersdown.bak/⁠ once no remaining vignette uses them.

Quarto vignettes, flow-style output: {...} headers and pkgdown-only articles in ⁠vignettes/articles/⁠ are listed but not changed: articles take the site default family unless you set output: albersdown::albers_vignette in their YAML by hand.

With method = "vendor" the stylesheet, script and fonts are copied into ⁠vignettes/⁠ and each vignette keeps rmarkdown::html_vignette with the theme's css and header include (the albersdown 2.0 setup).

Value

TRUE invisibly.

Examples

if (interactive()) {
  use_albersdown(path = ".", dry_run = TRUE)
}