Hierarchical Navigation & Auto-Discovery

Golem features an intelligent navigation discovery engine that builds sidebar navigation trees directly from your filesystem hierarchy.

Navigation Auto-Discovery Rules

Root Page Pinning: index.adoc in content_dir is always treated as the home/overview entry point.
Numeric Prefix Sorting: Files and directories prefixed with numbers (e.g. 01-introduction.adoc, 02-architecture.adoc) are sorted numerically, and the numeric prefix is automatically stripped in the UI menu title (Introduction, Architecture).
Explicit Weight Ordering (:nav_order:): AsciiDoc documents can declare their relative menu ordering using the :nav_order: header attribute.
Title Resolution: Golem extracts document titles from the top-level AsciiDoc header (= Document Title) rather than raw filenames.
Empty Directory Pruning: Directories that contain no .adoc source files are pruned from the navigation tree.

When auto-discovering navigation trees, Golem uses document metadata to establish reading hierarchy:

= Getting Started
:nav_order: 10
:idprefix:
:idseparator: -

Explicit :nav_order: weight: Documents and directory sections with lower numeric values appear first (e.g. 10 before 20).
Directory Section Weights: For a directory (e.g., user-guide/), Golem reads :nav_order: from its index.adoc (or readme.adoc) entry point to determine where the section appears relative to sibling sections.
Unordered Fallback: Items without :nav_order: default to a weight of 999 and are sorted alphabetically by filename.

If you prefer to define navigation order manually, specify nav in [navigation]:

[navigation]
nav = [
    "index.adoc",
    "guides/first-steps.adoc",
    "guides/advanced.adoc",
]