mkdocs.yml

site_name: Grove
site_description: Run your coding agents as a software factory, each task in its own workspace and tracked from ticket to trace.
repo_url: https://github.com/bearlike/Grove
repo_name: bearlike/Grove
site_url: https://bearlike.github.io/Grove/

theme:
  name: shadcn
  icon: logos/grove-logo.png
  favicon: logos/grove-logo.png

  # Ask AI panel, backed by DeepWiki on this repo. DeepWiki indexes the repo
  # automatically once it is public. Since theme v1.2 the greeting, avatar,
  # and WebMCP tool name all derive from site_name; no overrides needed.
  ai:
    deepwiki_repo: bearlike/Grove
    question_prefix: |
      I'm a new user; give product-first, well-grounded answers.
    examples:
      - "How do I install Grove?"
      - "How does the configuration cascade work?"
      - "What's the difference between pause and kill?"
      - "How do I add a custom agent?"

  versions_root: Grove
  show_version_switcher: true
  show_build_info: true

  # The Copy page menu (theme v1.26.0) links each page's Markdown source under
  # `repo_url`, and without this it infers the branch from the checkout. That
  # yields `main`, which is the Gitea branch: github.com/bearlike/Grove
  # publishes only `current`, so every View as Markdown / Open in ChatGPT /
  # Open in Claude link 404s. Measured: .../raw/main/docs/getting-started.md
  # is 404, .../raw/current/... is 200. This tracks the MIRROR's branch, so it
  # follows the publish branch rather than whatever is checked out here.
  source_ref: current

  # OFF because it renders INSIDE the masthead. The H1 label and the first H2
  # are one unit the theme spaces at 4px; the updated-date row lands between
  # them in the same flex column and adds its own 16px pad plus a 20px line,
  # measured 40px on `getting-started` against the 4px contract. A bare
  # `8/4/2026` at half opacity is not worth breaking the page's front door.
  # The footer still carries build info, which is the same signal with a home.
  show_datetime: false
  carousel: true
  sortable_tables: true
  code_refs: {}

  # This site is mostly screenshots of a terminal, and a TUI screenshot is
  # unreadable at column width. Every shot over 96px opens full screen on
  # click, and a carousel becomes one gallery rather than one entry per
  # cloned slide.
  lightbox: true

  # mkdocs rewrites and validates MARKDOWN links only. Every `<video poster=…>`
  # and hand-written `<a href=…>` on this site passes through verbatim, so a
  # relative prefix that is right on the landing page and wrong one level down
  # 404s in production behind a green `--strict` build. This resolves them
  # against the directory each page actually lands in; under `--strict` it
  # raises. Fix what it reports; never switch it back off.
  link_check: true

  # The nav's two halves are the site's whole IA, and until now they were only
  # visible once you looked at the sidebar. Page names here are flat, so `match`
  # prefixes do the routing that a directory layout would elsewhere.
  header_tabs:
    # `.` and not `/`. mkdocs' `url` filter passes an absolute path through
    # untouched, so `/` lands on the HOST root and leaves the docs site: this
    # site is served under `/grove/` on the internal host and `/Grove/` on
    # GitHub Pages, and neither is the server root. `.` relativizes per page.
    - label: Home
      icon: lucide:house
      url: home/
      match: [home]
    - label: User Guide
      icon: lucide:book-open
      url: getting-started/
      match: [getting-started, configure-, use-, features-, issue-ops, troubleshooting]
    - label: Developer Reference
      icon: lucide:code-xml
      url: develop-architecture/
      match: [develop-]

  nav_icons:
    Home: lucide:house
    "User Guide": lucide:book-open
    "Developer Reference": lucide:code-xml
    "Get Started": lucide:rocket
    Troubleshooting: lucide:life-buoy

    Configure: lucide:sliders-horizontal
    "Project Setup": lucide:folder-cog
    Agents: lucide:bot
    # The three agent pages take their vendors' own marks; the chooser above
    # them is vendor-neutral, so it gets a plain selection glyph.
    "Choosing an Agent": lucide:list-checks
    "Claude Code": simple-icons:claude
    Codex: simple-icons:openai
    OpenCode: simple-icons:opencode
    "Init Scripts": lucide:play
    "Ticket Providers": lucide:ticket
    "Configuration Reference": lucide:file-json

    Use: lucide:monitor-play
    "TUI Tour": lucide:layout-dashboard
    CLI: lucide:terminal
    "Web Dashboard": lucide:monitor-smartphone
    "Authentication & Pairing": lucide:key-round
    "MCP Server": lucide:plug
    "Issue Ops": lucide:message-square-code
    "Daily Workflow": lucide:workflow

    Capabilities: lucide:sparkles
    "Workspace Lifecycle": lucide:git-branch
    "Containerized Agents": lucide:container
    "Branch Provenance": lucide:shield-check
    "Agent Activity & Sessions": lucide:activity
    "Watches & Callbacks": lucide:alarm-clock
    "Telemetry & Tracing": lucide:waypoints
    "Feedback & Evaluations": lucide:message-square-check
    "Push Notifications": lucide:bell
    "Status Semantics": lucide:circle-dot
    "Configuration Cascade": lucide:layers
    "Diagram Collaboration": lucide:shapes
    "Attachments & Annotation": lucide:paperclip
    "Capability Catalog": lucide:list-checks

    Architecture: lucide:blocks
    "Public API": lucide:book-open-text
    "Engineering Principles": lucide:compass
    Contributing: lucide:git-pull-request

hooks:
  - docs/hooks/schema_to_md.py
  - docs/hooks/no_tracker_refs.py
  - docs/hooks/defer_vendor_scripts.py

# Order matters: the theme's authoring skill documents this sequence, and a
# missing extension degrades SILENTLY (a fence title prints as text, `++k++`
# prints literally, an abbreviation gets no underline) with nothing in the
# build to point at it.
markdown_extensions:
  - admonition
  # `extra` bundles abbr, attr_list, def_list, footnotes, md_in_html and
  # tables. abbr is the one that has to be asked for by name otherwise, and
  # the glossary below is worthless without it.
  - extra
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:
      use_pygments: true
      linenums: false           # off globally; pages opt in per fence
      css_class: codehilite     # the theme's CSS and copy button select on it
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.details
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.keys              # ++ctrl+k++ renders real <kbd> elements
  # `base_path` resolves from THIS file's directory, not `docs/`. `auto_append`
  # puts the abbreviation glossary on every page, so a term defined once gets
  # its tooltip wherever it is written.
  - pymdownx.snippets:
      base_path: [docs]
      auto_append: [_glossary.md]
  - shadcn.extensions.iconify
  - shadcn.extensions.hover_card

# `index.md` IS the animated landing page: it is the site root, so a visitor
# arriving at the published URL meets it first. It carries its own chrome and
# is not a sidebar entry -- the sidebar's Home is `home.md`, the documentation
# entry page the landing page's buttons lead to.
not_in_nav: |
  index.md

exclude_docs: |
  superpowers/
  _glossary.md
  hooks/
  # The landing scene's readable sources and the vendored Three.js build are
  # bundled into javascripts/grove-factory.min.js (tools/landing_bundle.py);
  # the page loads only the bundle, so publishing ~2 MB of inputs is waste.
  javascripts/grove-factory.js
  javascripts/factory/
  javascripts/vendor/
  design-system.md
  AGENTS.md
  CLAUDE.md
  # Folder READMEs describe the source tree for contributors. Without this,
  # mkdocs would publish docs/README.md as the site's index.
  README.md

plugins:
  - search
  - callouts:
      aliases: false
  - mkdocstrings:
      handlers:
        python:
          paths:
            - src
          options:
            docstring_style: google
            # The reference publishes the CONTRACT, not the implementation. A
            # source block renders the whole module verbatim, including every
            # inline comment — and comments are exactly where this repo keeps
            # its engineering archaeology (tracker refs, incident notes). No
            # docstring discipline can cover that, so the only enforceable line
            # is to not publish source at all; the repo itself is one click away.
            show_source: false
            show_signature_annotations: true
            show_root_heading: true
            show_root_toc_entry: false

extra:
  version:
    provider: mike

extra_css:
  - stylesheets/grove.css?v=5

nav:
  - Home: home.md
  - User Guide:
      - Get Started: getting-started.md
      - Use:
          - TUI Tour: use-tui.md
          - CLI: use-cli.md
          - Web Dashboard: use-webapp.md
          - Authentication & Pairing: use-auth.md
          - MCP Server: use-mcp.md
          - Issue Ops: issue-ops.md
          - Daily Workflow: use-workflow.md
      - Capabilities:
          - Capability Catalog: features-catalog.md
          - Attachments & Annotation: features-attachments.md
          - Diagram Collaboration: features-diagrams.md
          - Workspace Lifecycle: features-workspace-lifecycle.md
          - Containerized Agents: features-containers.md
          - Branch Provenance: features-branch-provenance.md
          - Ticket Providers: features-ticket-providers.md
          - Agent Activity & Sessions: features-activity.md
          - Watches & Callbacks: features-watches.md
          - Telemetry & Tracing: features-telemetry.md
          - Feedback & Evaluations: features-feedback-evals.md
          - Push Notifications: features-notifications.md
          - Status Semantics: features-status.md
          - Configuration Cascade: features-cascade.md
      - Agents:
          - Choosing an Agent: configure-agents.md
          - Claude Code: agents-claude-code.md
          - Codex: agents-codex.md
          - OpenCode: agents-opencode.md
      - Configure:
          - Project Setup: configure-project.md
          - Init Scripts: configure-init-scripts.md
          - Ticket Providers: configure-ticket-providers.md
          - Configuration Reference: configure-reference.md
      - Troubleshooting: troubleshooting.md
  - Developer Reference:
      - Architecture: develop-architecture.md
      - Public API: develop-public-api.md
      - Engineering Principles: develop-principles.md
      - Contributing: develop-contributing.md