Organizing Function Reference

Overview

qrtdown generates function documentation from your package’s .Rd files (created by roxygen2). By default, all exported functions are listed alphabetically. You can organize them into logical groups.

Default Behavior

Without configuration, reference.qmd lists all exported functions alphabetically with their titles. Each function links to its own detail page in the reference/ directory.

Grouping Functions

Organize functions into sections in _qrtdown.yml:

reference:
  sections:
    - title: "Main Functions"
      desc: "Core functionality"
      contents:
        - build_site
        - build_reference
        - build_articles

    - title: "Setup Functions"
      desc: "Initialize and configure"
      contents:
        - starts_with("use_")

    - title: "Utilities"
      contents:
        - ends_with("_sitrep")
        - matches("^clean_")

Section Fields

Field	Required	Description
title	Yes	Section heading
desc	No	Section description (shown below title)
contents	Yes	List of function names or patterns

Pattern Matching

Use these patterns in contents to match multiple functions:

Pattern	Matches	Example
function_name	Exact function name	build_site
starts_with("prefix")	Functions starting with prefix	starts_with("use_")
ends_with("suffix")	Functions ending with suffix	ends_with("_sitrep")
matches("regex")	Functions matching regex	matches("^build_")

Examples

contents:
  # Exact names
  - build_site
  - clean_site

  # All use_* functions
  - starts_with("use_")

  # All *_page functions
  - ends_with("_page")

  # Complex patterns
  - matches("^build_(site|home|reference)$")

Individual Function Pages

Each function gets its own page in reference/. These pages include:

• Title and description from roxygen2
• Usage - Function signature
• Arguments - Parameter documentation
• Details - Extended documentation
• Value - Return value description
• Examples - Code examples
• Source link - Link to the source code (if repository URL configured)

Source Links

To enable “Source” links on function pages, set your repository URL:

url: https://github.com/yourname/yourpackage

qrtdown finds where each function is defined and links to that file and line number.

Complete Example

url: https://github.com/yourname/mypackage

reference:
  sections:
    - title: "Building Documentation"
      desc: "Functions for building your documentation site"
      contents:
        - build_site
        - build_home
        - build_reference
        - build_articles
        - build_news
        - clean_site
        - preview_site

    - title: "Setup Helpers"
      desc: "usethis-style functions for initialization"
      contents:
        - starts_with("use_qrtdown")

    - title: "Conversion"
      desc: "Internal conversion utilities"
      contents:
        - rd_to_qmd
        - ends_with("_to_qmd")

    - title: "Diagnostics"
      desc: "Troubleshooting tools"
      contents:
        - qrtdown_sitrep

Tips

• Functions not matched by any section are not displayed, so make sure your patterns are complete
• Use matches(".") as a catch-all to include any remaining functions
• Order sections from most to least important
• Keep descriptions brief - one sentence is usually enough