Customizing Navigation

Navbar Structure

The navigation bar is configured in _qrtdown.yml. The default structure:

navbar:
  title: mypackage 0.1.0
  left:
  - text: Reference
    href: reference.qmd
  - text: Articles
  - text: Changelog
    href: NEWS.md
  right:
  - icon: code-square
    href: https://github.com/yourname/yourpackage
    aria-label: Source code

Left vs Right Navigation

• Left side: Primary navigation links (Reference, Articles, etc.)
• Right side: Secondary items like icons and external links

Adding Items

Text Links

navbar:
  left:
  - text: Get started
    href: vignettes/articles/getting-started.qmd
  - text: Reference
    href: reference.qmd

Icon Links

Use Bootstrap Icons for the right side:

navbar:
  right:
  - icon: github
    href: https://github.com/yourname/pkg
    aria-label: GitHub
  - icon: mastodon
    href: https://fosstodon.org/@yourname
    aria-label: Mastodon

Common icons: github, code-square, mastodon, twitter, rss, envelope.

The Articles Dropdown

The “Articles” navbar item is special. Just indicate it should exist:

navbar:
  left:
  - text: Articles

At build time, qrtdown:

1. Scans vignettes/articles/ for .qmd, .Rmd, and .md files
2. Extracts each article’s title from YAML front matter
3. Generates a dropdown menu automatically

If you have more than 5 articles, qrtdown shows the first 5 plus a “More articles…” link to the articles index page.

Adding Articles

use_qrtdown_article("new-feature", "New Feature Guide")
build_site()  # Article appears in dropdown automatically

Get Started Tab

Create a “Get started” article that gets its own navbar tab:

use_qrtdown_getting_started()

This creates vignettes/articles/{packagename}.qmd. Articles named after your package, “getting-started”, or “index” automatically get a separate navbar tab rather than appearing in the Articles dropdown.

Citation Link

The Citation link appears automatically when inst/CITATION exists:

use_qrtdown_citation()  # Creates inst/CITATION from DESCRIPTION
build_site()            # "Citation" link appears in navbar

No need to manually add it to your config.

Reordering Items

Simply change the order in your config:

navbar:
  left:
  - text: Get started
    href: vignettes/articles/mypackage.qmd
  - text: Articles
  - text: Reference
    href: reference.qmd
  - text: Changelog
    href: NEWS.md

Removing Items

Delete the item from the list. For example, to remove the Changelog:

navbar:
  left:
  - text: Reference
    href: reference.qmd
  - text: Articles
  # Changelog removed

Complete Example

navbar:
  title: "mypackage 0.1.0"

  left:
    - text: Get started
      href: vignettes/articles/mypackage.qmd
    - text: Reference
      href: reference.qmd
    - text: Articles
    - text: Changelog
      href: NEWS.md

  right:
    - icon: github
      href: https://github.com/yourname/mypackage
      aria-label: GitHub
    - icon: code-square
      href: https://codeberg.org/yourname/mypackage
      aria-label: Codeberg