mkdocs.yml

# Docs site config — Material for MkDocs. Renders docs/ as a navigable,
# searchable site at the Pages root. Each page lives in the folder naming its
# Diátaxis type, so the `nav:` below follows the tree rather than imposing an
# order over it (docs/contributing/documentation-standards.md § The hierarchy).
#
# Built in CI (release.yml deploy-pages job) into pages/ root; the web
# installer keeps its /install/ path untouched. Build locally with
#   uv run moondeck/docs/build_docs.py --strict
site_name: projectMM
site_description: High-performance LED & DMX lighting control for ESP32 and beyond.
# Canonical deployed URL: the custom domain, with the /projectMM/ repo subpath
# kept (GitHub Pages serves the project site under that path even on the custom
# domain — every existing link uses moonmodules.org/projectMM/…, e.g. the
# installer at /projectMM/install/). Drives the sitemap, canonical <link> tags,
# and the base for absolute URLs.
site_url: https://moonmodules.org/projectMM/
repo_url: https://github.com/MoonModules/projectMM
repo_name: MoonModules/projectMM
edit_uri: edit/main/docs/

# Flat output (foo.md → foo.html), NOT MkDocs' default directory URLs
# (foo.md → foo/index.html). The docs' relative links (image `<img src>`, source
# links) were hand-authored with `../` counts that match the FLAT layout — the
# same counts GitHub uses when viewing the raw .md. Directory URLs add one path
# level and break every relative asset link by one hop (a `../../../assets/…`
# preview resolves to `/moonmodules/assets/…` and 404s). Keeping flat URLs makes
# the same links resolve in BOTH the rendered site and GitHub's raw view — one
# link that works everywhere, no per-file rewrite.
use_directory_urls: false

theme:
  name: material
  # System fonts, not Material's default Roboto. The default loads from fonts.googleapis.com, which
  # sends every docs reader's IP to Google for a typeface nobody chose. Our privacy policy says
  # GitHub is who receives requests for these pages, and this is what keeps that true.
  font: false
  # The MoonModules moon-man — browser-tab favicon + the header logo (same PNG
  # the web installer uses, copied into docs/assets/). Paths are relative to docs/.
  favicon: assets/favicon.png
  logo: assets/favicon.png
  palette:
    # Dark theme matching the retired landing page's accent (#a78bfa).
    scheme: slate
    primary: deep purple
    accent: deep purple
  features:
    - navigation.instant   # SPA-style nav, no full reload
    - navigation.tracking  # URL reflects the active anchor
    - navigation.top       # back-to-top button
    # The ten top-level groups ride in a bar UNDER THE HEADER rather than stacking down the left
    # edge. Expanded in the sidebar they ran past a screen height, so the reader scrolled a menu to
    # find out what the site holds: the shape of the documentation was the thing hardest to see.
    # As tabs the ten are visible at once, and the sidebar narrows to the section being read.
    - navigation.tabs
    # Only the ACTIVE tab's pages in the sidebar, so its length follows one section rather than
    # the whole site. Needs navigation.tabs above to mean anything.
    - navigation.sections  # top-level nav groups render as sections
    - search.suggest
    - search.highlight
    - content.code.copy    # copy button on code blocks (matters once snippets land)

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.highlight:
      anchor_linenums: true
  # superfences also renders ```mermaid blocks as diagrams rather than code, via the
  # custom fence below: Material ships the mermaid runtime, so no extra dependency.
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.inlinehilite
  # Renders Material icon shortcodes (`:material-flash:` → the ⚡ glyph) used on
  # the landing page's buttons and card grid. Without this they show as literal
  # text. The emoji_index/generator pair is Material's documented icon setup.
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  # Snippets is the Phase-3 de-duplication mechanism: `--8<--` pulls real
  # source lines into a doc so a fact lives once (in the .h) and renders in
  # the .md. Enabled now (harmless with no snippets yet) so later phases need
  # no config change. base_path lets a snippet reference src/ from the repo root.
  - pymdownx.snippets:
      base_path: [!relative $config_dir]
      check_paths: true

plugins:
  - search

# Column widths + preview-image sizing for the catalog tables (see mkdocs_hooks.py).
extra_css:
  - assets/extra.css

# Build-time hooks (moondeck/docs/mkdocs_hooks.py): generate the test-inventory pages
# from the test files (never committed → can't drift), render each catalog page's
# prose ### blocks as a 4-column table, and rewrite out-of-docs source links to
# GitHub URLs. See the module docstring.
hooks:
  - moondeck/docs/mkdocs_hooks.py

# docs/work/ is internal (agent-facing, transient) — kept OFF the top
# nav (they're not in the `nav:` tree) but still BUILT into the site, so the many
# doc-to-doc links into them (a spec citing a design study, a decision record)
# resolve as normal relative links instead of 404ing. Reachable by following a
# link, not by browsing the menu. They're already public on GitHub. One build
# mechanism, no exclusion special-case, no dangling internal links.
# (The web installer is a separate top-level app outside docs_dir — MkDocs never
# sees it, so it needs no exclusion.)

# Link validation: warn (don't fail) on cross-doc anchors. The existing docs
# carry a backlog of links to renamed/removed section anchors — surfacing them
# is useful, but fixing ~400 of them is its own cleanup, not this additive
# site-standup. Phase 0 fails the build only on missing *files* / bad nav, not
# stale anchors. (A later phase can flip anchors to `error` once swept.)
validation:
  nav:
    omitted_files: ignore    # docs/work/ intentionally absent from nav
  links:
    not_found: warn
    anchors: warn
    absolute_links: ignore

# Top-down navigation over the existing files. Two audiences, in order:
# a user path first (what it is → install → use → effects), then the developer
# reference (architecture → modules → source-level). docs/work/ is
# internal and deliberately absent from the published site.
nav:
  - Home: index.md
  # A top-level tab, and the FILE stays at docs/gettingstarted.md: the web installer's Help
  # link is a hard-coded https://moonmodules.org/projectMM/gettingstarted.html, shipped
  # outside MkDocs, so the root URL is a contract rather than a layout choice.
  - Getting started:
      - Install & first light: gettingstarted.md
      # The web installer is a separate app deployed at /install/ (staged verbatim by the
      # release workflow, not built by MkDocs). A full URL (not a site-relative path) so
      # MkDocs treats it as the external resource it is.
      - Web installer: https://moonmodules.org/projectMM/install/
      # What MoonCloud IS to a user, kept apart from how it is built (Architecture > MoonCloud).
      # Two pages, two audiences: the device card deep-links this one from its consent prompt
      # (app.js, mooncloud.html#why-you-might-like-this), so its URL is a shipped contract.
      - MoonCloud: explanation/mooncloud.md
      - Log an issue: how-to/logging-an-issue.md
  # The FOLDER under docs/ is the Diataxis type: tutorials/, how-to/, explanation/,
  # reference/. The nav labels stay reader-facing, so the path tells a writer where a page
  # belongs while a reader never meets the word "explanation". The rules (contributing/)
  # and legal/ sit outside the grid on purpose — see contributing/documentation-standards.md.
  # ONE learning path, in the order a reader walks it: what it is, then building a show,
  # then making it beautiful, then writing your own. The install pages left for how-to/:
  # putting projectMM on a machine is a task somebody already has, not a lesson.
  - Tutorials:
      - How projectMM works: tutorials/how-projectmm-works.md
      - Build your first light show: tutorials/first-light-show.md
      - Write your first script: tutorials/first-script.md
      - Making beautiful effects: tutorials/generative-effects.md
      - Build your own MoonModules: tutorials/build-your-own-moonmodules.md
  # Diataxis keeps how-to guides apart from tutorials: a tutorial is a lesson for someone
  # learning, a how-to solves a task the reader already has.
  # Grouped by what the reader is trying to DO: get it running, wire the output, connect it
  # to something, keep it working.
  - How-to guides:
      - Installing on a desktop: how-to/installing-to-desktop.md
      - Running on a Linux machine: how-to/installing-on-linux.md
      - Building, running, flashing: how-to/building.md
      - Driving LED panels with a receiving card: how-to/panel-cards.md
      - LED signal integrity: how-to/led-signal-integrity.md
      - Driving projectMM from a phone or tablet: how-to/control-surface.md
      - Home automation: how-to/home-automation.md
      - Save and recall presets: how-to/presets.md
      - Updating firmware: how-to/updating-firmware.md
      - Back up and restore: how-to/backup-and-restore.md
      - Troubleshooting: how-to/troubleshooting.md
  - Lights:
      - Overview: moonmodules/light/index.md
      - Effects: moonmodules/light/effects.md
      - Layouts: moonmodules/light/layouts.md
      - Modifiers: moonmodules/light/modifiers.md
      - Drivers: moonmodules/light/drivers.md
      - MoonLive: moonmodules/light/moonlive.md
      - Power functions: moonmodules/light/power-functions.md
      - Supporting: moonmodules/light/supporting.md
  - Core:
      - System: moonmodules/core/system.md
      - Services: moonmodules/core/services.md
      - Supporting: moonmodules/core/supporting.md
      - Web UI: moonmodules/core/ui.md
  - Architecture:
      # "Overview", not the section's own name: the tab already says Architecture, and a first
      # child repeating it reads as a page about the tab rather than the way into it. The
      # convention is for INDEX pages only: a section whose first child is real content keeps
      # that page's own title, which says what it is ("Install & first light", "Testing strategy").
      - Overview: explanation/architecture/index.md
      - MoonModule: explanation/architecture/moonmodule.md
      - MoonCore: explanation/architecture/mooncore.md
      # The reference half of MoonCore's platform abstraction, so it sits beside it rather than
      # carrying a tab of its own. The file stays under moonmodules/ because the generated
      # moxygen/ tree is written beside it (gen_api.py writes moonmodules/<domain>/moxygen/).
      - Platform: moonmodules/platform/index.md
      - MoonLight: explanation/architecture/moonlight.md
      - MoonLive: explanation/architecture/moonlive.md
      - MoonBase: explanation/architecture/moonbase.md
      - MoonInstaller: explanation/architecture/mooninstaller.md
      - MoonCloud: explanation/architecture/mooncloud.md
      - MoonDeck: explanation/architecture/moondeck.md
      - Why we write our own code: explanation/why-we-write-our-own.md
  - Reference:
      - Testing strategy: reference/testing.md
      - Performance: reference/performance.md
      # The CMake layout, moved out of the how-to: a tree to look up, not a step to follow.
      - Build system: reference/build-system.md
      - Migrating (breaking changes): reference/MIGRATING.md
      # Generated by moondeck/check/repo_health.py on every KPI-gate run — the size/LOC/
      # docs ratchet. Next to Performance because both are measured state, not prose.
      - Repo health: reference/metrics/repo-health.md
      # Generated by check_docgen.py --report: what the documentation sweep has left.
      - Docgen: reference/metrics/docgen.md
      - Unit tests: reference/tests/unit-tests.md
      - Scenario tests: reference/tests/scenario-tests.md
      - Hardware:
          - Firmware variants and memory: reference/hardware/firmware-variants.md
          - GPIO usage per MCU: reference/hardware/gpio-usage.md
          - ESP32-S31 coreboard: reference/hardware/esp32-s31-coreboard.md
          - MHC-WLED ESP32-P4 shield: reference/hardware/mhc-wled-esp32-p4-shield.md
          - Light fixtures and DMX nodes: reference/hardware/light-fixtures.md
          - Control surfaces: reference/hardware/control-surfaces.md
  # The rules bind a contributor rather than serving a reader need, so they sit outside
  # the Diataxis grid (contributing/documentation-standards.md § The hierarchy).
  - Contributing:
      - Principles & process: contributing/principles-and-process.md
      - Coding standards: contributing/coding-standards.md
      - Documentation standards: contributing/documentation-standards.md
  - Legal:
      - Privacy policy: legal/privacy-policy.md

# The per-module summary pages above (Effects & building shows › Supporting, Core ›
# UI/Supporting) are the docs-v2 surface: each 4-column table row links to the module's
# generated technical page (moonmodules/{core,light}/moxygen/<Module>.md, from each `.h`'s
# /// comments) and, temporarily during the migration, to the original hand-written page.
# Those per-module pages still BUILD and are reachable by link, but are OFF the menu.