# 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

```yaml
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.

```yaml
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

```yaml
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.

```yaml
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

```yaml
# 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
```