Package {quartodown}

Build the package website

Description

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

Usage

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

Arguments

Details

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, if it isn't 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 the same as 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. 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, if not from 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 darkly.

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

• 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)

Preview the built site

Description

Serves ⁠docs/⁠, as built by build_site(), in a web browser, and reloads the page when the site is rebuilt. 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).

Usage

preview_site(path = ".")

Arguments

Value

The server, invisibly; see servr::httw().

Examples

## Not run: 
build_site()
preview_site()

## End(Not run)

Set up a package to use quartodown

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

An existing ⁠_quartodown.yml⁠ 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. ⁠_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)

Set up a GitHub Actions workflow that publishes the site

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)