Getting Started

Quick Start

library(qrtdown)

# Initialize qrtdown in your package
use_qrtdown()

# Build the site
build_site()

# Preview in browser
preview_site()

Coming from pkgdown?

qrtdown handles articles differently than pkgdown. Here’s what you need to know:

	pkgdown	qrtdown
Article location	vignettes/	vignettes/articles/
File format	.Rmd	.qmd (or .Rmd, .md)
R CMD check	Vignettes are built	Articles are ignored
Config	Manual in _pkgdown.yml	Auto-discovered

Migration Steps

1. Create the articles directory:

   dir.create("vignettes/articles", recursive = TRUE)

2. Move your vignettes:

   # Move all .Rmd files to articles/
   fs::file_move(
     fs::dir_ls("vignettes", glob = "*.Rmd"),
     "vignettes/articles/"
   )

3. Convert to .qmd (optional but recommended):

   # Rename .Rmd to .qmd
   for (f in fs::dir_ls("vignettes/articles", glob = "*.Rmd")) {
     fs::file_move(f, fs::path_ext_set(f, "qmd"))
   }

4. Remove vignette engine headers:

   pkgdown vignettes have engine metadata that qrtdown articles don’t need:

   # REMOVE this from your articles:
   vignette: >
     %\VignetteIndexEntry{Title}
     %\VignetteEngine{knitr::rmarkdown}

5. Build:

   use_qrtdown()
   build_site()

Why vignettes/articles/?

R treats files in vignettes/ as package vignettes. During R CMD check, R tries to build them, which can cause issues:

• Vignettes need special YAML headers
• Build failures block package submission to CRAN
• Long-running examples slow down checks

By placing website content in vignettes/articles/, qrtdown keeps your documentation separate from R’s vignette system. The articles/ subdirectory is ignored by R but rendered by qrtdown.

Important: If you put .qmd files directly in vignettes/ (not in the articles/ subdirectory), qrtdown will not find them.

Creating Articles

The “Get started” Article

Create the main introductory article for your package:

use_qrtdown_getting_started()

This creates vignettes/articles/{packagename}.qmd and adds a separate “Get started” tab in the navbar (not in the Articles dropdown). This follows the pkgdown convention.

Regular Articles

For additional articles that appear in the Articles dropdown:

use_qrtdown_article("my-article", title = "My Article Title")

This creates vignettes/articles/my-article.qmd with proper YAML front matter.

Linking to Articles

From README or Other Articles

Use relative paths with the .qmd extension:

See the [getting started guide](vignettes/articles/getting-started.qmd) for examples.

Why .qmd extension?

• On the website: Quarto automatically converts to .html
• On GitHub/Codeberg: The link points to the viewable source file

This works well when your README content is shared between the repository and website.

Shared README Content

A common pattern is sharing content between your GitHub/Codeberg README and website homepage. Create a partial file:

your-package/
├── README.qmd           # Renders to README.md for repository
├── _readme-body.qmd     # Shared content (links, features, examples)
└── index.qmd            # Website homepage (can include _readme-body.qmd)

README.qmd:

---
format: gfm
---

# mypackage

{{< include _readme-body.qmd >}}

index.qmd (generated by qrtdown, or create manually):

---
title: mypackage
---

{{< include _readme-body.qmd >}}

With this setup, links like [guide](vignettes/articles/guide.qmd) work in both contexts.

Configuration

Minimal Setup

After running use_qrtdown(), you get a _qrtdown.yml:

url: https://github.com/yourname/yourpackage
template:
  theme: cosmo

That’s often all you need. qrtdown auto-discovers:

• Articles in vignettes/articles/
• Citation from inst/CITATION
• Changelog from NEWS.md
• Logo from man/figures/logo.png

Common Customizations

Change theme:

template:
  theme: flatly

Add external links:

navbar:
  right:
  - icon: globe
    href: https://yoursite.com
    aria-label: Website

What NOT to Do

Don’t manually list articles with explicit paths:

# DON'T do this - paths won't work as expected
navbar:
  left:
  - text: Articles
    menu:
    - text: Guide
      href: vignettes/guide.qmd  # Wrong! Should be vignettes/articles/

Instead, just indicate Articles should exist:

# DO this - qrtdown fills in the menu automatically
navbar:
  left:
  - text: Articles

qrtdown scans vignettes/articles/ and builds the dropdown menu for you.

Images and Static Assets

qrtdown automatically copies images to your built site. Here’s where to store them.

Where to Put Images

Location	Use Case	How to Reference
man/figures/	Logo and README images	
vignettes/articles/images/	Article images	

Package Logo

Store your logo at man/figures/logo.png (or .svg). It appears automatically in the navbar.

usethis::use_logo("path/to/your-logo.png")

README Images

For images in your README, use man/figures/:

your-package/
├── README.md
└── man/
    └── figures/
        ├── logo.png
        └── screenshot.png

Reference in README.md:

![Screenshot](man/figures/screenshot.png)

Article Images

For images in articles, create an images/ folder inside vignettes/articles/:

vignettes/articles/
├── getting-started.qmd
├── advanced-usage.qmd
└── images/
    ├── diagram.png
    ├── screenshot.png
    └── workflow.png

Reference in any article:

![](images/diagram.png)

How It Works

qrtdown configures Quarto to copy these directories to your output:

• man/figures/** - All package figures
• vignettes/articles/** - All article subdirectories (including images/)

This happens automatically when you run build_site().

Troubleshooting

Articles not appearing?

1. Check location: Files must be in vignettes/articles/, not vignettes/
2. Check extension: Must be .qmd, .Rmd, or .md
3. Check for underscore: Files starting with _ are ignored (they’re partials)
4. Rebuild: Run build_site() to regenerate the navbar

Links broken on website?

1. Use .qmd extension in links, not .html
2. Use correct path: vignettes/articles/name.qmd from root
3. Check file exists: The target file must be in vignettes/articles/

Site looks different when running quarto render directly?

Always use build_site(). It regenerates _quarto.yml with current content. Running quarto render directly may use stale configuration.

Run diagnostics

qrtdown_sitrep()

This shows: - Quarto version and path - What content was detected - What pages will be generated - Navbar structure

Deploying Your Site

qrtdown supports automatic deployment via CI (recommended) or manual deployment.

How Automatic Deployment Works

The use_qrtdown_*_pages() functions create CI workflow files. They do not deploy your site directly. Instead:

1. You run the setup function once (creates the workflow file)
2. You commit and push the workflow file to your repository
3. You enable CI in your repository settings
4. From then on: Every push to main automatically rebuilds and deploys your site

You never need to manually build or deploy again - just push your code.

GitHub Pages

use_qrtdown_github_pages()

What it does: Creates .github/workflows/qrtdown.yaml

One-time setup after running:

1. Commit and push the workflow file to GitHub
2. Go to repository Settings > Pages
3. Set Source to “GitHub Actions”
4. Done! Future pushes to main auto-deploy

Codeberg Pages

Codeberg Pages serves static content directly from a pages branch - no CI is required:

# Build and deploy
build_site()
deploy_site()

One-time setup after first deploy:

1. Go to repository Settings > Pages
2. Set branch to pages
3. Your site will be at https://<username>.codeberg.page/<repo>/

Manual Deployment

If you prefer to control when the site updates (or don’t want CI):

# Build locally
build_site()

# Push docs/ to the pages branch
deploy_site(branch = "pages")

Run these commands each time you want to update your site.

Next Steps

• Configuration Guide - Detailed configuration options
• ?build_site - Function documentation
• ?use_qrtdown_article - Creating articles programmatically