Organize Reference Page

Group and organize your API reference documentation

Organize Reference Page

By default, QuartoDocBuilder lists all documented functions alphabetically. You can organize them into logical groups using ReferenceGroup.

Basic Grouping

reference = [
    ReferenceGroup(
        title = "Core Functions",
        contents = [:main_func, :helper_func, :process_data]
    ),
    ReferenceGroup(
        title = "Utilities",
        contents = [:format_output, :validate_input]
    )
]

config = QuartoConfig(
    module_name = MyPackage,
    reference = reference
)

Using Selectors

Instead of listing every function, use pattern-based selectors:

starts_with

Match functions by name prefix:

ReferenceGroup(
    title = "Data Processing",
    contents = [starts_with("process_")]  # process_data, process_file, etc.
)

ends_with

Match functions by name suffix:

ReferenceGroup(
    title = "Utilities",
    contents = [ends_with("_util")]  # format_util, string_util, etc.
)

matches

Use regex patterns:

ReferenceGroup(
    title = "Getters & Setters",
    contents = [matches(r"^(get|set)_")]  # get_value, set_config, etc.
)

contains

Match substring anywhere in name:

ReferenceGroup(
    title = "Helper Functions",
    contents = [contains("helper")]  # my_helper, string_helper_func, etc.
)

Combining Selectors

Mix explicit symbols with selectors:

ReferenceGroup(
    title = "Data I/O",
    contents = [
        :read_data,              # Explicit symbol
        :write_data,             # Explicit symbol
        starts_with("load_"),    # All load_* functions
        starts_with("save_")     # All save_* functions
    ]
)

Adding Descriptions

Each group can have a description:

ReferenceGroup(
    title = "Configuration",
    desc = "Functions for setting up and configuring the package.",
    contents = [:QuartoConfig, :ThemeConfig, :load_config]
)

Complete Example

reference = [
    ReferenceGroup(
        title = "Configuration",
        desc = "Types and functions for configuring documentation.",
        contents = [:QuartoConfig, :SectionConfig, :ThemeConfig,
                   :load_config, :default_config]
    ),
    ReferenceGroup(
        title = "Site Building",
        desc = "Core functions for generating documentation sites.",
        contents = [:quarto_build_site, starts_with("quarto_")]
    ),
    ReferenceGroup(
        title = "Content Selectors",
        desc = "Helpers for organizing reference pages.",
        contents = [:starts_with, :ends_with, :matches, :contains]
    ),
    ReferenceGroup(
        title = "Utilities",
        contents = [ends_with("_util"), contains("helper")]
    )
]

Automatic Grouping

If you don’t specify reference, QuartoDocBuilder auto-groups by type:

• Functions - All function symbols
• Types - All struct/type definitions
• Constants - All constant values

# This will auto-group
config = QuartoConfig(
    module_name = MyPackage,
    reference = []  # Empty = auto-group
)

Order Matters

Functions are assigned to the first matching group. Order your groups from most specific to most general:

reference = [
    # Specific first
    ReferenceGroup(title = "Core", contents = [:main_func]),

    # Pattern-based second
    ReferenceGroup(title = "Processing", contents = [starts_with("process_")]),

    # Catch-all last
    ReferenceGroup(title = "Other", contents = [matches(r".*")])
]

Documenting submodules

By default only bindings documented directly in module_name are included. If your package nests documented bindings in submodules, set include_submodules:

config = QuartoConfig(
    module_name = MyPackage,
    include_submodules = true,
)

With this enabled, the reference page, the individual function pages, and the emitted objects.inv all include the submodule bindings. When include_submodules = false and a submodule contains documented bindings, a warning tells you they were skipped.

Collision-safe page names

Page file names stay unique even when two modules define the same name. A name that is unique keeps its bare file name (foo.qmd). When two bindings share a name, the one owned directly by the root module keeps foo.qmd while the others get a qualified name from their submodule path — a foo in MyPackage.Inner becomes Inner.foo.qmd. Reference-page links and autolinks point at these collision-safe names automatically, so navigation never lands on the wrong page.

The same names are used by reference_page_names, which you can call directly if you need the mapping. The selector and grouping helpers (filter_objects, group_objects, autodocs_group, …) all accept a recursive keyword that mirrors include_submodules.