# 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: MoonLight
site_description: High-performance LED & DMX lighting control for ESP32 and beyond.
# Canonical deployed URL: the custom domain, with the /MoonLight/ repo subpath
# kept (GitHub Pages serves the project site under that path even on the custom
# domain: every existing link uses moonmodules.org/MoonLight/…, e.g. the
# installer at /MoonLight/install/). Drives the sitemap, canonical <link> tags,
# and the base for absolute URLs.
site_url: https://moonmodules.org/MoonLight/
repo_url: https://github.com/MoonModules/MoonLight
repo_name: MoonModules/MoonLight
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
  # Momo, the MoonModules mascot: browser-tab favicon and 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
    # The address keeps the anchor a link opened, since MoonWalk reads it as the process to show; scroll tracking would rewrite it.
    - 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

# The stage files and their schema are not under docs/, and the map the docs serve is built from them: a change there rebuilds the site.
watch:
  - moonwalk

plugins:
  - search
  # A page MoonWalk took over keeps its address: each old URL forwards to its process in the live view, so links from the installer, the README and the help still land.
  - redirects:
      redirect_maps:
        work/past/lessons.md: contributing/lessons.md
        work/future/analysis-code-hosting.md: design/code-hosting.md
        work/future/analysis-effects-power-functions-inventory.md: design/effects-power-functions-inventory.md
        work/future/analysis-input-mapping.md: design/input-mapping.md
        work/future/analysis-leddriver.md: design/leddriver.md
        work/future/analysis-moonlive.md: design/moonlive.md
        work/future/analysis-small-boards.md: design/small-boards.md
        work/future/analysis-ui-extensibility.md: design/ui-extensibility.md
        work/future/analysis-virtual-layer-downscale.md: design/virtual-layer-downscale.md
        reference/tests/unit-tests.md: reference/tests.md
        reference/tests/scenario-tests.md: reference/tests.md
        reference/metrics/code.md: reference/tests.md#check_code
        reference/metrics/docgen.md: reference/tests.md#check_docgen
        reference/metrics/prose.md: reference/tests.md#check_prose
        tutorials/first-light-show.md: moonwalk.md#first-light-show
        how-to/installing-to-desktop.md: moonwalk.md#install
        how-to/building.md: moonwalk.md#desktop-build-test
        gettingstarted.md: getting-started.md
        moonmodules/light/index.md: explanation/how-moonlight-works.md
        reference/hardware/small-boards.md: design/small-boards.md
        tutorials/how-moonlight-works.md: explanation/how-moonlight-works.md
        tutorials/generative-effects.md: explanation/generative-effects.md
        how-to/updating-firmware.md: moonwalk.md#update-firmware
        # The how-to folder became MoonWalk's processes; each page's facts moved to reference/, and its old address keeps working.
        how-to/installing-on-linux.md: reference/installing-on-linux.md
        how-to/adding-a-stream-source.md: reference/adding-a-stream-source.md
        how-to/audio-input.md: reference/audio-input.md
        how-to/watching-the-output.md: reference/watching-the-output.md
        how-to/control-surface.md: reference/control-surface.md
        how-to/home-automation.md: reference/home-automation.md
        how-to/presets.md: reference/presets.md
        how-to/migrating-over-the-air.md: reference/migrating-over-the-air.md
        how-to/backup-and-restore.md: reference/backup-and-restore.md
        how-to/troubleshooting.md: reference/troubleshooting.md
        how-to/faq.md: reference/faq.md
        how-to/logging-an-issue.md: reference/logging-an-issue.md
        how-to/panel-cards.md: reference/hardware/panel-cards.md
        how-to/led-drivers.md: reference/hardware/led-drivers.md
        how-to/hub75-panels.md: reference/hardware/hub75-panels.md
        how-to/hold-to-play.md: reference/examples/hold-to-play.md
        how-to/multi-board-installation.md: reference/examples/multi-board-installation.md
        how-to/led-signal-integrity.md: reference/troubleshooting.md#stray-pixels-or-wrong-colors-on-lights-that-should-be-off
        explanation/led-signal-integrity.md: reference/troubleshooting.md#stray-pixels-or-wrong-colors-on-lights-that-should-be-off

# The site's styles: colored headings, the card deck, the clips.
extra_css:
  - assets/extra.css

# The card deck (assets/help-deck.js), a module that mounts on any page holding a .mm-deck.
extra_javascript:
  - path: assets/help-deck.js
    type: module
  # MoonWalk's journey map (assets/moonwalk.js): its button on every page, and the map on moonwalk.md.
  - path: assets/moonwalk.js
    type: module
  # The test page (assets/tests.js): a module that mounts on the page holding #mm-tests.
  - path: assets/tests.js
    type: module

# Build-time hooks (moondeck/docs/mkdocs_hooks.py): publish the test registry
# from the test files (never committed, so it cannot 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. Installers already shipped link gettingstarted.html for help, a contract the redirect above keeps.
  - Getting started:
      - Getting started: getting-started.md
      # What a new user reads after the first install: the cards, the pipeline, live changes.
      - How MoonLight works: explanation/how-moonlight-works.md
      # Every clip of the series in watching order, each linking the page it plays on.
      - Videos: videos.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/MoonLight/install/
      # Answers to what people hit on a first run, each from someone's bench: the first hour's reader asks.
      - FAQ: reference/faq.md
      - Troubleshooting: reference/troubleshooting.md
      - Log an issue: reference/logging-an-issue.md
      - Contributing: contributing/index.md
      # The two tutorials: a first MoonLive script, typed into the browser, and a first C++ effect for a developer new to the code.
      - Write your first script: tutorials/first-script.md
      - Build your own MoonModules: tutorials/build-your-own-moonmodules.md
      - Security: explanation/security.md
      - Privacy policy: legal/privacy-policy.md
  # The pages drawn from the code and the tests rather than written, each a tab of its own and so page-wide (mkdocs_hooks.on_page_markdown): the catalogs, the processes, the tests and the credits.
  - Effects: moonmodules/light/effects.md
  - Modifiers: moonmodules/light/modifiers.md
  - Layouts: moonmodules/light/layouts.md
  - Drivers: moonmodules/light/drivers.md
  - Services: moonmodules/core/services.md
  - System: moonmodules/core/system.md
  - MoonWalk: moonwalk.md
  - Tests: reference/tests.md
  - Attributions: reference/attributions.md
  # The FOLDER under docs/ is the Diataxis type: tutorials/, explanation/ and reference/, with the how-tos as MoonWalk's processes. 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: contributing/documentation-standards.md.
  # Users and integrators: running it, connecting it, the hardware it runs on.
  - Reference:
      # What the steps of MoonWalk's processes rest on, grouped by what the reader is doing: running it, connecting it, keeping it working.
      - Using it:
          - Running on a Linux machine: reference/installing-on-linux.md
          - Presets: reference/presets.md
          - Back up and restore: reference/backup-and-restore.md
          - Migrating over the air: reference/migrating-over-the-air.md
          - Control surfaces: reference/control-surface.md
          - Home automation: reference/home-automation.md
          - Audio input: reference/audio-input.md
          - Watching the output as video: reference/watching-the-output.md
          # What MoonCloud IS to a user, kept apart from how it is built (Developers > Architecture > MoonCloud). 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
          # Its reader is a user upgrading: the action to take per break.
          - Migrating (breaking changes): reference/MIGRATING.md
      # The question a user arrives with: how do I drive this from my own code rather than from the page.
      - Scripting and integrating:
          - MoonLive: moonmodules/light/moonlive.md
          - Making beautiful effects: explanation/generative-effects.md
          - Integrating: reference/integrating.md
          - REST API: reference/api.md
      - Light pipeline modules: moonmodules/light/supporting.md
      - Examples:
          - Playing an effect while a button is held: reference/examples/hold-to-play.md
          - The StadBeest, a multi-device installation: reference/examples/multi-board-installation.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
          - LightCrafter 16: reference/hardware/lightcrafter-16.md
          - MHC-WLED ESP32-P4 shield: reference/hardware/mhc-wled-esp32-p4-shield.md
          - Waveshare ESP32-P4-ETH: reference/hardware/esp32-p4-eth.md
          - Teensy 4.1: reference/hardware/teensy-4-1.md
          - Light fixtures and DMX nodes: reference/hardware/light-fixtures.md
          - Control surfaces: reference/hardware/control-surfaces.md
          - LED drivers: reference/hardware/led-drivers.md
          - HUB75 panels: reference/hardware/hub75-panels.md
          - Receiving cards for LED panels: reference/hardware/panel-cards.md
          - TV backlight: reference/hardware/tv-backlight.md
  # Contributors: how it is built, the rules, and the references a change needs.
  - Developers:
      - Architecture:
          # "Overview", not the section's own name: a first child repeating the section reads as a page about it rather than the way in.
          - Overview: explanation/architecture/index.md
          - MoonModule: explanation/architecture/moonmodule.md
          - MoonCore: explanation/architecture/mooncore.md
          # The reference half of MoonCore's platform abstraction, beside it.
          - Platform: moonmodules/platform/index.md
          - Core internals: moonmodules/core/supporting.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
          - MoonWalk: explanation/architecture/moonwalk.md
          - Web UI: moonmodules/core/ui.md
      - Why we write our own code: explanation/why-we-write-our-own.md
      # Pre-decision surveys, each cited by the card or plan it informs; a study leaves once its topic ships.
      - Design studies:
          - Overview: design/index.md
          - Code hosting: design/code-hosting.md
          - Effects on the power functions: design/effects-power-functions-inventory.md
          - Input mapping: design/input-mapping.md
          - LED drivers: design/leddriver.md
          - MoonLive roadmap: design/moonlive.md
          - Small boards: design/small-boards.md
          - UI extensibility: design/ui-extensibility.md
          - Render larger, pool down: design/virtual-layer-downscale.md
      # The bugs and fixes MoonLight waits on in the projects it builds on, each with its workaround and when it goes.
      - Issues in other projects: reference/issues-in-other-projects.md
      - Power functions: moonmodules/light/power-functions.md
      - Picture and channel-data sources: reference/adding-a-stream-source.md
      - Testing strategy: reference/testing.md
      - Performance: reference/performance.md
      # The CMake layout: a tree to look up, not a step to follow.
      - Build system: reference/build-system.md
      # Generated by moondeck/check/repo_health.py on every KPI-gate run, next to Performance because both are measured state.
      - Repo health: reference/metrics/repo-health.md
      - MoonWalk reference: reference/moonwalk.md
      # The rules bind a contributor rather than serving a reader need (contributing/documentation-standards.md § The hierarchy); the way in is Getting started > Contributing.
      - Rules:
          - Principles & process: contributing/principles-and-process.md
          - Coding standards: contributing/coding-standards.md
          - Documentation standards: contributing/documentation-standards.md

# The catalog pages above are drawn from the module headers through docs/help/help.json, and each card links its header on GitHub, the technical reference.