mdcms/docs/reference-nav.md

nav.yml reference

nav.yml is generated by mdcms build. Do not write it from scratch — run the build command and edit the result.

python3 mdcms.py build --path app/

What is preserved on rebuild: All manual edits to section metadata fields (defaultname, sort, parent, parent-sort, pagesvisibility, categorynames) survive a rebuild. Page entries are re-generated from frontmatter each time.

What is overwritten on rebuild: Page title, sort, section-id — these are always taken from frontmatter.

---

Top-level structure

sections:
  - code: my-section
    defaultname: My Section
    sort: 100
    pagesvisibility: visible

pages:
  - file: pages/my-page.md
    title: My Page
    section-id: my-section
    sort: 100

---

sections

Each section groups a set of pages under a heading in the nav. Sections are auto-created from section-id values found in page frontmatter.

sections:
  - code: guides              # Internal identifier. Set via section-id in page frontmatter.
                              # Letters, numbers, hyphens, underscores. Not shown to users.

    defaultname: Guides       # Display name shown in the nav.
                              # Auto-generated from code on first build; edit freely after.

    sort: 100                 # Controls section ordering in the nav (lower = higher).
                              # Sections without a sort value sort to the bottom.

    pagesvisibility: visible  # Controls page visibility for this section.
                              # visible  — pages appear in nav and search (default).
                              # hidden   — pages are hidden from nav but included in search.
                              # draft    — pages hidden from nav AND excluded from search.

    parent: getting-started   # Optional. Makes this section a child of another section.
                              # Value is the code of the parent section.

    parent-sort: 50           # Sort position of this section within its parent.
                              # Required when parent is set.

    categorynames:            # Per-category section display names.
                              # Required when categories-sectionnames: per-category in config.yml.
      en: Guides
      nb: Veiledninger
      ar: أدلة

Section example — nested

sections:
  - code: getting-started
    defaultname: Getting Started
    sort: 100
    pagesvisibility: visible

  - code: installation
    defaultname: Installation
    sort: 100
    pagesvisibility: visible
    parent: getting-started
    parent-sort: 10

  - code: configuration
    defaultname: Configuration
    sort: 200
    pagesvisibility: visible
    parent: getting-started
    parent-sort: 20

---

pages

Page entries are generated from markdown frontmatter. The fields below are written by the build and read by the renderer.

pages:
  - file: pages/home.md       # Path relative to site root. Written by build — do not change.

    title: Home               # Page title. Taken from frontmatter title: on each build.

    section-id: guides        # Assigns the page to a section. Taken from frontmatter.
                              # Omit to leave the page unsectioned (appears above all sections in nav).

    sort: 100                 # Nav ordering within its section (lower = higher).
                              # Taken from frontmatter sort: on each build.

Note: Pages are sorted within their section by sort, then alphabetically by filename as a tiebreaker. Draft pages (frontmatter draft: true) are excluded entirely from nav.yml and search.json.

---

How sections and pages connect

1. Add section-id: my-section to a page's frontmatter.
2. Run mdcms build — the section is auto-created in nav.yml with defaultname derived from the code.
3. Edit defaultname, sort, pagesvisibility in nav.yml as needed. These edits are preserved on future rebuilds.

---

Full example

# nav.yml — generated by mdcms
# Manual edits to section metadata (defaultname, sort, parent, parent-sort,
# pagesvisibility, categorynames) are preserved on rebuild.

sections:
  - code: getting-started
    defaultname: Getting Started
    sort: 100
    pagesvisibility: visible

  - code: reference
    defaultname: Reference
    sort: 200
    pagesvisibility: visible

  - code: advanced
    defaultname: Advanced Topics
    sort: 300
    pagesvisibility: hidden   # pages exist but are not shown in the nav

  - code: changelog
    defaultname: Changelog
    sort: 400
    pagesvisibility: visible
    parent: reference
    parent-sort: 99

pages:
  - file: pages/home.md
    title: Home
    sort: 100

  - file: pages/quickstart.md
    title: Quick Start
    section-id: getting-started
    sort: 100

  - file: pages/install.md
    title: Installation
    section-id: getting-started
    sort: 200

  - file: pages/config-reference.md
    title: Configuration Reference
    section-id: reference
    sort: 100

  - file: pages/api.md
    title: API Reference
    section-id: reference
    sort: 200

  - file: pages/internals.md
    title: Internals
    section-id: advanced
    sort: 100

  - file: pages/v04.md
    title: v0.4
    section-id: changelog
    sort: 100