mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
74681670d7
All keys, all values, usage instructions, and full examples for each file. https://claude.ai/code/session_01UP8Wo2CKPNhvvTkzX48CWF
185 lines
5.2 KiB
Markdown
185 lines
5.2 KiB
Markdown
# 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
|
|
```
|