Package 'quartodown'

Description

Builds the package website into ⁠docs/⁠ with Quarto.

Usage

build_site(
  path = ".",
  tooltips = TRUE,
  freeze = FALSE,
  quiet = TRUE,
  devel = FALSE,
  workers = 1,
  preview = interactive()
)

Arguments

Details

The site is built in a scratch folder, ⁠_quarto/_site/⁠, and replaces the one in ⁠docs/⁠ only once it is complete. So the previous site stays there, and viewable with preview_site(), while the build runs and if it fails.

build_site() assembles a Quarto website project in ⁠_quarto/⁠ from the package sources and ⁠_quartodown/_quartodown.yml⁠, then renders it. It uses README.md (or, without one, DESCRIPTION), ⁠man/⁠, the vignettes (including those in subfolders), NEWS.md, LICENSE/LICENSE.md, and CODE_OF_CONDUCT.md, CONTRIBUTING.md and SUPPORT.md (at the top level or in ⁠.github/⁠). See vignette("quartodown") for what the site contains.

While it builds, the environment variable IN_QUARTODOWN is "true", so the package's examples and vignettes can check identical(Sys.getenv("IN_QUARTODOWN"), "true"). IN_QUARTODOWN_PKG is the name of the package whose site it is, which code shared between packages can check.

Value

Invisibly, the path to the built site.

Configuration

⁠_quartodown/_quartodown.yml⁠ is optional; use_quartodown() creates one. It can contain:

• url: the site's address. It defaults to the first URL in DESCRIPTION that isn't a source repository.

• reference: the sections of the function reference index and the topics each lists, by name or with selectors such as starts_with(). The format is based on pkgdown's.

• navbar: the items on the navbar's left and right: keywords such as reference and articles, vignettes, and Quarto navbar items and menus; and the icons in its tools, by default repo. With style: sidebar, the left items go in a sidebar instead, with a link to every reference page.

• home: file, the .md or .qmd file the home page shows instead of README.md; sidebar, the sidebar's structure (its sections, in order) and components (sections of your own), or false to show the page as written, without it; and links, added to the sidebar's links.

• authors: by a person's name, an href to link it and html to replace it; and under sidebar and footer, the roles shown, with before/after text in the sidebar and text in the footer.

• repo: the repository's urls (home, and the prefixes of links to a file, source; an issue, issue; and a user, user) and branch. They default to those of DESCRIPTION's GitHub, GitLab or Codeberg URL.

• theme: the light and dark themes: names of Quarto's built-in themes, such as flatly and darkly, or .scss files in ⁠_quartodown/⁠. By default, default and a dark version of it.

• redirects: pairs of paths, from an old page to the one replacing it, such as ⁠["reference/old.html", "reference/new.html"]⁠.

• development: mode, release (the default) to build the site into ⁠docs/⁠, or devel to build a site for the development version into ⁠docs/dev/⁠, next to the released version's; unreleased marks the version as unreleased, and auto picks from the version number and whether the package is on CRAN. The environment variable QUARTODOWN_DEV_MODE overrides it. The format is based on pkgdown's. Content in .quartodown-devel or .quartodown-release shows on only that site.

• vignettes: files, files and folders outside ⁠vignettes/⁠ that the vignettes use by a relative path, such as ⁠man/rmd/⁠ for a child document ../man/rmd/shared.Rmd, copied with them.

• logo: false to leave the logo, man/figures/logo.svg or .png (and in light mode logo-light, if it exists), off the pages' titles.

• quarto: settings merged over the generated Quarto configuration.

⁠_quartodown/extra.scss⁠ and ⁠_quartodown/extra.css⁠, if they exist, style every page, on top of quartodown's theme. The whole ⁠_quartodown/⁠ folder is copied into the Quarto project, so quarto settings can refer to other files in it by the same path.

See vignette("customizing", package = "quartodown") for the details.

Examples

## Not run: 
use_quartodown()
build_site()

## End(Not run)

Description

Serves ⁠docs/⁠ (or ⁠docs/dev/⁠, for a development site; see the Configuration section of build_site()), as built by build_site(), in a web browser. The server keeps running for the rest of the R session and is reused by later calls, including build_site()'s (which, with a server already running, leaves the open page to reload instead of opening another). It keeps serving the previous site while build_site() runs. An open page reloads if the new build changed it.

Usage

preview_site(path = ".")

Arguments

Value

The site's local URL, invisibly.

Examples

## Not run: 
build_site()
preview_site()

## End(Not run)

Description

Writes ⁠_quartodown/_quartodown.yml⁠, the configuration file build_site() reads. It starts with a ⁠reference:⁠ field listing every function currently documented in ⁠<path>/man/*.Rd⁠ in one "All functions" section. Also adds the .gitignore/.Rbuildignore entries the build needs (see Details) if they're not already there.

Usage

use_quartodown(path = ".")

Arguments

Details

In a package with a pkgdown configuration (⁠_pkgdown.yml⁠, also in ⁠pkgdown/⁠), it's translated instead, with any files it needs, such as ⁠_quartodown/extra.scss⁠, and the settings that couldn't be translated are listed. See "Coming from pkgdown" in vignette("customizing", package = "quartodown").

An existing ⁠_quartodown.yml⁠, or file in ⁠_quartodown/⁠, is never overwritten.

use_quartodown() adds the following lines to .gitignore and .Rbuildignore (only the ones not already present in each file):

# .gitignore
_quarto/*
!_quarto/_freeze/

# .Rbuildignore
^docs$
^_quarto$
^_quartodown$

⁠_quarto/⁠ is the Quarto project build_site() generates and renders into ⁠docs/⁠. Its ⁠_freeze/⁠ directory holds the results of code run with build_site(freeze = TRUE), which can be committed so later builds, e.g. on CI, reuse them (they aren't rerun when only the package's code or its dependencies change, so delete it to refresh them). ⁠_quartodown/⁠ holds the site's configuration and any files it uses, such as extra.scss.

Value

Invisibly, the path to ⁠_quartodown/_quartodown.yml⁠.

Examples

pkg <- tempfile("examplepkg")
dir.create(pkg)
write(
  "Package: examplepkg\nVersion: 0.0.0.9000",
  file.path(pkg, "DESCRIPTION")
)
use_quartodown(pkg)
readLines(file.path(pkg, "_quartodown", "_quartodown.yml"))
unlink(pkg, recursive = TRUE)

Description

Writes .github/workflows/quartodown.yaml, a GitHub Actions workflow that builds the site and deploys it to the gh-pages branch. It runs build_site() on every push, pull request and release, but only deploys when it isn't a pull request. Also adds ⁠^\.github$⁠ to .Rbuildignore if it's not already there.

Usage

use_quartodown_action(path = ".", overwrite = FALSE)

Arguments

Details

Once the workflow's first run has created the gh-pages branch, go to the Pages section of the repository's settings on GitHub and choose to deploy from that branch.

Value

Invisibly, the path to the workflow file.

Examples

pkg <- tempfile("examplepkg")
dir.create(pkg)
write(
  "Package: examplepkg\nVersion: 0.0.0.9000",
  file.path(pkg, "DESCRIPTION")
)
use_quartodown_action(pkg)
list.files(pkg, recursive = TRUE, all.files = TRUE)
unlink(pkg, recursive = TRUE)