Customizing your site

If you want to customize your site, you can do so by editing _quartodown/_quartodown.yml, which quartodown::use_quartodown() creates. The _quartodown/ folder at the package root also holds the files that style the site. _quartodown.yml has twelve fields, all optional:

• url: is the site’s address. It defaults to the first URL in DESCRIPTION that isn’t on GitHub, GitLab or Codeberg.
• reference: groups and orders the function reference index.
• navbar: lays out the navbar.
• home: picks the home page’s source and lays out its sidebar.
• authors: links authors’ names and picks who is shown where.
• repo: says where the source code is. It defaults to the GitHub, GitLab or Codeberg URL (or BugReports) in DESCRIPTION.
• theme: picks the light and dark themes.
• redirects: sends visitors from old addresses to new ones.
• development: builds a separate development site.
• vignettes: lists files the vignettes use.
• logo: turns off the logo by each page’s title.
• quarto: changes any other Quarto setting.

The reference index

Without reference:, the index lists every function in one section. To group them, list the sections:

reference:
1  - title: Read and write
2    desc: Functions for getting data in and out.
    contents:
3      - read_data
4      - starts_with("write_")
  - title: Helpers
5    subtitle: Low-level
    contents:
      - has_concept("helpers")
6      - -internal_helper

1

Each entry becomes a section of the index, with this heading.

2

Optional Markdown text, shown under the heading.

3

A topic, by any of its \alias{} names or its Rd file name.

4

A selector.

5

An optional heading one level below title.

6

A leading - removes a topic.

The selectors are:

A topic that no section lists is left off the index with a warning, but still gets a page. A topic with \keyword{internal} is left off without a warning, and gets no page. To change that:

• To hide a topic from the index without the warning, list it in a section titled internal, which isn’t shown.
• To show an internal topic on the index, name it in a section, as you would for roxygen’s reexports, or select it with internal = TRUE, as in starts_with("dev_", internal = TRUE). This gives it a page too.
• To give an internal topic a page but keep it off the index, list it in the section titled internal. To do this for all of them, use has_keyword("internal"):

reference:
  - title: Read and write
    contents:
      - read_data
  - title: internal
    contents:
      - has_keyword("internal")

The format is based on pkgdown’s reference:.

The navbar

navbar: lists the items on the navbar’s left and right, in order, and under tools the icons right of the search box. The default is:

navbar:
  left: [intro, reference, articles, news]
  right: []
  tools: [repo]

Each of these is a keyword that quartodown turns into an item, and leaves out if the package has nothing for it:

Any other item is a vignette, given as its path relative to vignettes/ without extension and linked with its title, or a Quarto navbar item. tools takes only icons: repo or a Quarto tool. Inside a Quarto item’s menu:, vignettes are given the same way, and a folder ending in / lists every vignette in it.

For example, with the vignettes in a folder for each menu:

navbar:
  left:
    - reference
    - news
    - text: Get started
      menu:
1        - get-started/installation
        - get-started/first-steps
    - text: User guide
2      menu: user-guide/
    - text: Developers
      menu:
        - dev/internals
3        - text: Contributing
          href: CONTRIBUTING.md
  right:
    - text: Blog
      href: https://example.com/blog
  tools:
    - repo
    - icon: mastodon
      text: Mastodon
      href: https://fosstodon.org/@me

1

vignettes/get-started/installation.qmd.

2

Every vignette in vignettes/user-guide/, sorted by file name.

3

Any Quarto navbar item works in a menu too.

Vignettes can live in any subfolder of vignettes/. Files and folders whose name starts with _ or . are skipped, as Quarto does.

Every vignette is built, even one the navbar doesn’t link to. Such a vignette can only be reached through links from other pages, so build_site() warns about it, unless the navbar has articles, which lists every vignette nothing else links.

A sidebar instead

With style: sidebar, the left items move into a sidebar beside every page, and the navbar keeps the site’s title, the search box, the right items and the tools:

navbar:
  style: sidebar

Menus become sections of the sidebar, and “Reference” lists every reference page by function name, with a section for each titled group of reference:. The gallery shows what it looks like.

The home page

The home page shows README.md, or, if there is none, the package’s description from DESCRIPTION. To give the site a different home page than the README, use home: file: at another file, relative to the package root:

home:
  file: index.qmd

It can be Markdown (.md) or a Quarto document (.qmd), whose code runs when the site is built, as in a vignette. Write links and image paths in it relative to the package root, as in the README.

Next to the page, a sidebar shows the package’s links, license, community files, citation, authors and badges. sidebar: can reorder its sections, drop some, or add your own, and links: adds to its links:

home:
  links:
    - text: Blog
      href: https://example.com/blog
  sidebar:
1    structure: [links, funding, license, authors]
    components:
2      funding:
        title: Funding
        text: Supported by [a grant](https://example.com).

1

The sections, in order. The built-in ones are links, license, community, citation, authors and dev (the README’s badges); by default, all of them in that order, then your own.

2

A section of your own: a heading and Markdown text.

For full control over the page you can turn the sidebar off with sidebar: false:

home:
  file: index.qmd
  sidebar: false

The page then shows the file as written. Like any other page, it then gets a table of contents, which toc: false in its front matter can turn off.

Authors

The home page’s sidebar and the footer list the authors with the roles aut, cre and fnd from DESCRIPTION’s Authors@R, and the authors page lists everyone. authors: can link a person’s name, or replace it with HTML such as a logo, and change who is shown:

authors:
1  Jane Doe:
    href: https://jane.example.com
  Acme Inc:
    href: https://acme.example.com
    html: <img src="https://acme.example.com/logo.png" alt="Acme" height="24">
  sidebar:
2    roles: [aut, cre]
3    after: Thanks to all [contributors](authors.html).
  footer:
    roles: [cre]
4    text: Maintained by

1

A person, by their name as in Authors@R.

2

The roles shown in the sidebar.

3

Markdown shown under the sidebar’s list, or with before: above it.

4

Instead of “Developed by”.

The format is based on pkgdown’s authors:.

The repository

Links to the package’s source code, issues and contributors come from the first GitHub, GitLab (also self-hosted, if the host name contains gitlab) or Codeberg URL in DESCRIPTION’s URL, or else from its BugReports. For a package in a subfolder, give the folder’s URL, such as https://github.com/me/repo/tree/main/mypkg.

repo: changes the branch the source links point to:

repo:
  branch: devel

or sets the links directly, such as for another host:

repo:
  url:
1    home: https://git.sr.ht/~me/mypkg
2    source: https://git.sr.ht/~me/mypkg/tree/main/item/
3    issue: https://todo.sr.ht/~me/mypkg/
4    user: https://sr.ht/~

1

The repository’s page.

2

Prefix of links to files, such as R/foo.R. Overrides branch:.

3

Prefix of links to issues.

4

Prefix of links to users.

The format is based on pkgdown’s repo:.

Redirects

When a page moves, such as a function’s reference page after it is renamed you can use redirects: so links to the old address keeps working. Each entry is a pair: the old address and the new one, both relative to the site’s root:

redirects:
  - ["reference/foo.bar.html", "reference/foo_bar.html"]
  - ["articles/old-guide.html", "vignettes/guide.html"]

For a vignette, Quarto’s own aliases: in its front matter does the same.

Development and release sites

By default, every build replaces the site. To keep the site for the version on CRAN and have a second one, at dev/, for the development version, with a switch next to the navbar’s title to go between them, set development: mode::

development:
  mode: auto

Remember to bump the version to .9000 right after each release to avoid the release version of docs to be overwritten!

Content for only one of the two sites can be set in a .quartodown-release or .quartodown-devel div or span:

::: {.quartodown-release}
Install the released version from CRAN with `install.packages("mypkg")`.
:::

::: {.quartodown-devel}
Install the development version with `pak::pak("me/mypkg")`.
:::

With mode: auto, a package not yet on CRAN keeps the .quartodown-devel content.

Files the vignettes use

The vignettes are built from a copy of vignettes/ in _quarto/vignettes/, so a relative path out of it, such as read.csv("../data-raw/example.csv"), can’t find the file. List such files and folders under vignettes: files:, and they are copied too, to the same paths:

vignettes:
  files:
    - data-raw/example.csv

Documents in them aren’t rendered as pages. When a vignette has a quoted ../ path to a file that isn’t copied, the build warns and names the entry to add.

Other Quarto settings

quartodown writes a Quarto configuration into _quarto/_quarto.yml (overwritten on every build). The quarto: field is merged over it, key by key:

• A list of entries, such as website: navbar: left:, is added to.
• Any other value is replaced.
• ~ removes a setting.

For example, to fold code blocks, drop the table of contents and change the footer:

quarto:
  format:
    html:
      code-fold: true
      toc: ~
  website:
    page-footer:
      right: "Built with love."

See the Quarto website reference for the full list of changes you can make.

quarto: applies to every page. To change a single vignette instead, set the option in its front matter, which overrides the site-wide value:

---
title: "A long tutorial"
format:
  html:
    code-fold: true
    toc-depth: 3
---

To change a single code chunk, use a chunk option such as #| code-fold: true.

Styling and layout

The site uses Quarto’s default theme in light mode and a dark version of it in dark mode. theme: picks others from Quarto’s built-in themes, with quartodown’s styling on top:

theme:
  light: flatly
  dark: darkly

A theme can also be your own .scss file in _quartodown/, such as light: _quartodown/brand.scss. To adjust a built-in theme, use extra.scss (see below).

To restyle every page, add _quartodown/extra.scss. It applies to both the light and the dark theme, and has two sections:

• scss:defaults sets variables, such as colors and fonts, that the theme uses throughout.
• scss:rules holds CSS rules, which can use those variables.

/*-- scss:defaults --*/
1$primary: #2c7a7b;
$font-family-sans-serif: "Inter", sans-serif;

/*-- scss:rules --*/
.navbar {
2  border-bottom: 1px solid $border-color;
}

1

Links, the active navbar item and buttons.

2

$border-color is the light theme’s in light mode and the dark theme’s in dark mode.

Plain CSS can go in _quartodown/extra.css instead, which is added to every page as it is.

The page’s widths and spacing are Quarto settings, under quarto:. For example, a wider text column and table of contents:

quarto:
  format:
    html:
      grid:
        body-width: 900px
        margin-width: 300px

See Quarto’s page layout guide for grid: and page-layout:.

The logo

The package’s logo, man/figures/logo.svg (or logo.png), shows right of every page’s title, except on pages that show it already, such as a home page whose README has it in its title. If there is also a man/figures/logo-light.svg (or .png), light mode shows that one instead. The site’s favicon is logo.png (or logo.svg). To leave the logo off the pages:

logo: false

The navbar’s items start where the page’s text does, which a script on each page measures. To start them at the edge of the page instead, override it with:

/*-- scss:rules --*/
.navbar-container {
  padding-left: 1em !important;
}

Everything in _quartodown/ is copied into the Quarto project, so other files it holds can be named from quarto: by the same path, such as Quarto template partials:

quarto:
  format:
    html:
      template-partials:
        - _quartodown/title-block.html

Setting include-in-header: or include-after-body: replaces quartodown’s own files, which, among other things, pick dark mode for visitors who prefer it and line up the navbar. To add to them, list them too:

quarto:
  format:
    html:
      include-in-header:
        - quartodown-header.html
        - _quartodown/analytics.html

Coming from pkgdown

In a package with a _pkgdown.yml, use_quartodown() translates it into _quartodown/_quartodown.yml, and lists the settings it couldn’t translate. Fields with a similar format are copied: url:, reference:, home: sidebar:, home: links:, authors:, repo:, redirects: and development: mode:. The rest maps as follows:

Vignettes are published under vignettes/ rather than articles/, and the changelog is NEWS.html rather than news/index.html, so the translation adds redirects: from pkgdown’s addresses.

A separate home page (an index.md used instead of the README) isn’t picked up automatically: set it with home: file:. Code that checks IN_PKGDOWN (or pkgdown::in_pkgdown()) should check identical(Sys.getenv("IN_QUARTODOWN"), "true") instead.