---
title: "Get started with quartodown"
vignette: >
  %\VignetteIndexEntry{Get started with quartodown}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

quartodown builds a website for an R package with [Quarto](https://quarto.org/).
This guide sets up a package, builds its site, and publishes it on GitHub Pages.

## Set up

From the root of your package, run:

```r
quartodown::use_quartodown()
```

This writes `_quartodown/_quartodown.yml`, and adds the files the build
generates to `.gitignore` and `.Rbuildignore`. `_quartodown.yml` is where you
can [customize your
site](https://bjarkehautop.github.io/quartodown/vignettes/customizing.html). If
your package already has a `_pkgdown.yml`, see [Coming from
pkgdown](https://bjarkehautop.github.io/quartodown/vignettes/customizing.html#coming-from-pkgdown)
for how its settings carry over.

## Build the site

```r
quartodown::build_site()
```

`build_site()` builds the site into `docs/` and, in an interactive session,
opens it in your browser. The page reloads when you rebuild, and
`preview_site()` opens it again if you've closed it. Examples and vignettes run
against your package's current source. While iterating,
`build_site(devel = TRUE)` is faster because it loads the package with
`pkgload::load_all()` instead of installing it.

The following is added to your site:

- **Home page**: your `README.md`. Next to it, a sidebar links to the source
  code, the bug tracker and CRAN (if the package is there), and shows the
  license, citation and authors from `DESCRIPTION`. Any badges in your README
  (between `<!-- badges: start -->` and `<!-- badges: end -->`) are moved into
  the sidebar.
- **Reference**: a page for each help topic in `man/`, plus an index page
  listing them all.
- **Get started**: the vignette with the same name as your package, like this
  one.
- **Articles**: all your other vignettes, including any in subfolders such as
  `vignettes/articles/`.
- **Changelog**: your `NEWS.md`. Issue numbers like `#123` and GitHub usernames
  like `@user` become links.

## Publish on GitHub Pages

To build the site and deploy it to the `gh-pages` branch on every push, add a
GitHub Actions workflow:

```r
quartodown::use_quartodown_action()
```

This writes `.github/workflows/quartodown.yaml`. Commit and push it. Once its
first run has created the `gh-pages` branch, go to the *Pages* section of your
repository's settings on GitHub and choose to deploy from that branch.

## Learn more

[Customizing your
site](https://bjarkehautop.github.io/quartodown/vignettes/customizing.html)
covers everything `_quartodown.yml` can change.

[Quarto
features](https://bjarkehautop.github.io/quartodown/vignettes/articles/showcase.html)
shows Quarto's authoring features, such as callouts, tabsets and footnotes, on a
quartodown site.

[Technical
details](https://bjarkehautop.github.io/quartodown/vignettes/articles/technical.html)
explains how a build works.