mkdocs-nav

Skill: Sync mkdocs.yml nav

Parent: AGENTS.md

Keep the nav: section in mkdocs.yml in sync with the files that actually exist under doc/. Run this whenever a new doc is added and needs to appear on https://exelearning.github.io/exelearning/.

---

0. Before you start

Read these two sources in full:

1. mkdocs.yml — current nav and site config.
2. All .md files under doc/ — use Glob with doc/**/*.md.

Do not skip any file. The goal is a nav that references every .md file exactly once.

---

1. Identify gaps

List every .md path returned by the glob. Normalize paths to forward slashes and strip the doc/ prefix (MkDocs paths are relative to docs_dir: doc).

Compare with every path already referenced under nav: in mkdocs.yml.

Report which files are missing from the nav and which nav entries point to files that no longer exist (stale entries). Both must be fixed.

---

2. Assign each doc to a section

Use the table below to decide where each file belongs. When in doubt, read the first two lines of the file for its title and description.

Ordering within each section

Top level (in this order):

1. Home (index.md)
2. Overview (overview.md)
3. Install (install.md)
4. Profile Avatars (profile-avatars.md)
5. Deployment (deployment.md)
6. High Availability (high-availability.md)
7. Deploy: Sample Configs (deploy/README.md)
8. Architecture (architecture.md)
9. Conventions (conventions.md)

Development (alphabetical by label, except Environment first): Environment → Version Control → Contributing → Testing → Internationalization → Real Time → Embedding → Profiling → Customization → Styles → Installers → REST API → Authentication

File Formats (Legacy ELP first, then ELPX):

1. Legacy ELP Format (contentv3-format.md)
2. ELPX Format (elpx-format.md) — then subsections in this order:
   • Container & XML group: Container → content.xml → IDs → Metadata → Pages & Blocks
   • iDevices subsection: Catalog → Patterns → config.xml → Snippets
   • Resources group: Themes → Libraries → Assets → Screenshot
   • Pipelines group: Tracking → Export Pipeline → Import Pipeline → Validation
   • AI Generation
   • Examples subsection: Minimal → Multi-page → Full Package Tree

If a new file appears that doesn't match any entry above, add it to the most logical section and note your choice as a comment in your response.

---

3. Write the updated mkdocs.yml

Preserve everything outside the nav: block exactly as-is (theme, plugins, markdown_extensions, extra, validation, etc.). Only replace the nav: block.

Use 2-space indentation inside nav: (MkDocs convention). Labels must be human-readable title case.

Target structure (expand as needed to include every file):

nav:
  - Home: index.md
  - Overview: overview.md
  - Install: install.md
  - Profile Avatars: profile-avatars.md
  - Deployment: deployment.md
  - High Availability: high-availability.md
  - Deploy\: Sample Configs: deploy/README.md
  - Architecture: architecture.md
  - Conventions: conventions.md
  - Development:
      - Environment: development/environment.md
      - Version Control: development/version-control.md
      - Contributing: development/contributing.md
      - Testing: development/testing.md
      - Internationalization: development/internationalization.md
      - Real Time: development/real-time.md
      - Embedding: development/embedding.md
      - Profiling: development/profiling.md
      - Customization: development/customization.md
      - Styles: development/styles.md
      - Installers: development/installers.md
      - REST API: development/rest-api.md
      - Authentication: development/authentication.md
  - File Formats:
      - Legacy ELP Format: contentv3-format.md
      - ELPX Format:
          - Overview: elpx-format.md
          - Container: elpx-format/container.md
          - content.xml: elpx-format/content-xml.md
          - IDs: elpx-format/ids.md
          - Metadata: elpx-format/metadata.md
          - Pages & Blocks: elpx-format/pages-blocks.md
          - iDevices:
              - Catalog: elpx-format/idevices/catalog.md
              - Patterns: elpx-format/idevices/patterns.md
              - config.xml: elpx-format/idevices/config-xml.md
              - Snippets: elpx-format/idevices/snippets.md
          - Themes: elpx-format/themes.md
          - Libraries: elpx-format/libraries.md
          - Assets: elpx-format/assets.md
          - Screenshot: elpx-format/screenshot.md
          - Tracking: elpx-format/tracking-emission.md
          - Export Pipeline: elpx-format/export-pipeline.md
          - Import Pipeline: elpx-format/import-pipeline.md
          - Validation: elpx-format/validation.md
          - AI Generation: elpx-format/ai-generation.md
          - Examples:
              - Minimal content.xml: elpx-format/examples/minimal-content-xml.md
              - Multi-page content.xml: elpx-format/examples/multi-page-content-xml.md
              - Full Package Tree: elpx-format/examples/full-package-tree.md

Important: The colon in Deploy: Sample Configs must be escaped as \: inside a YAML mapping key. Alternatively, quote the key: "Deploy: Sample Configs". Either is correct YAML; prefer the quoted form for readability.

After writing the file, re-read it and confirm the YAML is valid (no duplicate keys, consistent indentation).

---

4. Report back

Tell the user:

1. Which files were added to the nav (list them).
2. Which entries were removed as stale (list them, if any).
3. Which files, if any, you placed in a section not listed in the table above, and why.
4. Any file you skipped and the reason (e.g., it is a doc/style.css or non-Markdown asset — those should never appear in the nav).

Do not modify any file other than mkdocs.yml.