Architecture Overview

How QuartoDocBuilder is structured internally

Architecture Overview

QuartoDocBuilder is designed to be modular and extensible. This document explains the internal architecture.

Core Components

1. Configuration System (config.jl)

The configuration system provides type-safe structs for all settings:

  • QuartoConfig - Main configuration struct
  • SectionConfig - Navbar section configuration
  • ReferenceGroup - Reference page grouping
  • ThemeConfig - Theme and appearance settings
  • FooterConfig - Footer customization

2. Content Selectors (selectors.jl)

Inspired by R’s pkgdown, selectors allow flexible organization of reference pages:

# Match functions by name patterns
starts_with("process_")  # All functions starting with "process_"
ends_with("_util")       # All functions ending with "_util"
matches(r"^get")         # Regex matching
contains("helper")       # Contains substring

3. Docstring Processing (quarto_format.jl)

Converts Julia docstrings to Quarto-compatible markdown. The renderer is structure-agnostic — it dispatches on each Markdown node’s type — so it:

  • re-fences code blocks as julia,
  • demotes docstring headers by two levels,
  • maps admonitions to the matching Quarto callout type,
  • falls back to Markdown.plain for anything else.

See Docstring Processing for the full mapping.

4. Site Building (build.jl)

The main build orchestrator:

  1. Generates _quarto.yml configuration (including a resources: objects.inv entry)
  2. Creates section directories and index files
  3. Generates the reference index and a page for each documented binding
  4. Creates navigation structure (navbar, sidebars)
  5. Emits docs/objects.inv so other packages can cross-link back
  6. Post-processes the generated pages to autolink cross-references (when autolink = true)
  7. Validates internal links (failing the build when strict = true)

5. Inventories and Auto-linking (inventory.jl, autolink.jl)

Reads and writes Sphinx objects.inv inventories and turns backticked names into links — both within the package and, via registered inventories, to other packages. See Cross-package Links.

6. Articles System (articles.jl)

Discovers and organizes content files:

  • Auto-discovers .qmd files in section directories
  • Extracts titles and metadata from YAML frontmatter
  • Sorts by order field or alphabetically

Data Flow

                    ┌─────────────────┐
                    │  QuartoConfig   │
                    └────────┬────────┘
                             │
            ┌────────────────┼────────────────┐
            │                │                │
            ▼                ▼                ▼
    ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
    │  _quarto.yml  │ │   reference/  │ │   sections/   │
    │  (navbar,     │ │   (function   │ │   (tutorials, │
    │   sidebars)   │ │   docs)       │ │   guides)     │
    └───────────────┘ └───────────────┘ └───────────────┘
            │                │                │
            └────────────────┼────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │  Quarto render  │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │   HTML Site     │
                    └─────────────────┘

Extension Points

Custom Selectors

You can create custom selector functions:

# Create a selector that matches documented functions only
my_selector = sym -> begin
    obj = getfield(MyModule, sym)
    return obj isa Function && hasmethod(obj, Tuple{})
end

Custom Theme

Extend the theme with custom CSS/SCSS:

theme = ThemeConfig(
    bootswatch = "flatly",
    custom_css = """
    .my-custom-class {
        color: red;
    }
    """
)

Dependencies

QuartoDocBuilder keeps its dependency footprint small:

  • Markdown, REPL, TOML (Julia standard library) - docstring parsing and configuration
  • Downloads (standard library) - fetching remote objects.inv inventories
  • CodecZlib - zlib (de)compression for the objects.inv format

The CodecZlib and Downloads dependencies were added in 0.4.0 to support Sphinx inventories for cross-package linking.