# Template canônico de mkdocs.yml para apps — copie para a raiz do repo do app
# e troque <app> pelo slug do app (confira o slug: ele é o ID público, para sempre).
# Fonte da verdade: https://fonte.xadm.biz/xadm/documentacao (templates/mkdocs.yml)
# Padrão: https://docs.xadm.biz/padroes/publicar-docs/
site_name: <app>
site_url: https://docs.xadm.biz/aplicacoes/<app>/

theme:
  name: material
  language: pt-BR
  # overrides/main.html traz o aviso de "versão antiga" do seletor de versão
  # (doc versionada — decisão 0004). Copie templates/overrides-main.html para
  # overrides/main.html no repo do app.
  custom_dir: overrides
  palette:
    primary: custom
    accent: custom
  features:
    - navigation.sections
    - navigation.path       # breadcrumbs: "onde estou" ao chegar via busca
    - navigation.footer     # links Anterior/Próximo no rodapé (ler como livro, §1.7)
    - search.suggest
    - search.highlight

# Logo/título do header voltam para o portal central (constituição §5)
extra:
  homepage: https://docs.xadm.biz/
  # Seletor de versão no topo (doc versionada por release — decisão 0004 / spec 011).
  # O docs.yml builda cada versão com site_url terminando na versão e publica em
  # docs-sites/<app>/<versão>/; o publica-versao.py monta o versions.json na raiz.
  version:
    provider: mike

# Identidade visual X-Adm (azul royal + prata, derivada do logo) — copie docs/stylesheets/xadm.css
# de um app existente ou do repo central.
extra_css:
  - stylesheets/xadm.css

# ▲ UMA ÚNICA chave `exclude_docs:` no arquivo — YAML não avisa sobre chave
# repetida: a última **sobrescreve** a primeira em silêncio, e o `--strict` fica
# verde. Uma segunda chave aqui embaixo apagaria o `privado/` e publicaria
# confidencial de cliente (aconteceu: constituição 0.24.0→0.24.2). Precisa excluir
# mais alguma coisa? Some uma linha a ESTE bloco; nunca abra outro.
#
# privado/ é segmento RESERVADO: qualquer pasta privado/ em docs/ é
# confidencial e jamais sai no site (constituição §5) — NÃO remova esta
# exclusão. anexos/privado/ é o lar padrão. Doc legada que ainda não migrou
# ao padrão pode ser listada no mesmo bloco (migração oportunista).
#
# Arquivo-fato NÃO é página: é fragmento que uma página embute com `--8<--`
# (constituição §1.9). Por isso `exclude_docs` e não `not_in_nav` — este último só
# cala o aviso de órfã, e o fragmento continua sendo BUILDADO: vira página pública
# com H1 inventado do nome do arquivo ("Xadm ingest") e entra na busca, devolvendo
# o mesmo texto duas vezes (uma na hospedeira, outra na órfã). O `--8<--` continua
# transcluindo normalmente — ele lê do disco, não do build.
#   _importado/  = fatos baixados de OUTROS repos no build; efêmeros (.gitignore).
#                  Sem isto, o site do consumidor serve o contrato do dono como se
#                  fosse página dele — a cópia que a §1.9 existe para matar.
#   public/contratos/ = fatos DESTE repo que outros consomem; quem os mostra é a
#                  hospedeira `public/contratos/index.md` (publicar-docs.md).
exclude_docs: |
  privado/
  /_importado/**
  /public/contratos/*.md
  !/public/contratos/index.md

# Cabeçalho de governança (Status/Responsável/Atualizado) a partir do
# frontmatter — o docs.yml baixa o hook do site central antes do build
# (fonte única, igual ao valida-frontmatter.py). NÃO remova o hooks: sem
# remover também o passo de download no docs.yml, senão o build falha.
hooks:
  - scripts/frontmatter-cabecalho.py
  # Documentação Completa: processa os marcadores do livro AUTORADO
  # (projeto/index.md, constituição §2) — injeta <!-- etapas --> (Resumo
  # Executivo) e <!-- GERADO: changelog --> (livro), e FALHA o build em
  # <!-- RECONCILIAR --> não resolvido. O docs.yml baixa este hook do site
  # central antes do build (igual ao de cima).
  - scripts/visao-tecnica.py

plugins:
  - search:
      lang: pt
  # OpenAPI público: a página docs/public/api/index.md embute o spec com
  # <swagger-ui src="openapi.yaml"/>. Só relevante se o app expõe API (§5).
  - swagger-ui-tag
  # Página única / PDF (constituição §2): concatena na ordem do nav — a Visão
  # técnica vem primeiro, então lê como overview → detalhes. DEVE ser o ÚLTIMO
  # plugin — depois do swagger-ui-tag; fora de ordem o print-site quebra o
  # `mkdocs build --strict`.
  - print-site:
      add_to_navigation: true
      print_page_title: "Tudo numa página"

# Referência de API gerada (Javadoc/dartdoc) é copiada para dentro de docs/ antes
# do build (docs.yml) e tem centenas de arquivos — declará-los aqui evita o ruído
# "não está no nav" no --strict. O link para ela é Markdown normal (valida).
# `not_in_nav` é o certo aqui: o Javadoc PRECISA sair no site, só não no índice.
not_in_nav: |
  /dev/api/**

markdown_extensions:
  - admonition              # blocos !!! note / warning
  - attr_list               # atributos {...} — botões, classes
  - def_list                # definition lists — o glossário usa
  - tables
  - toc:
      permalink: true
  # Embeds --8<-- : a Documentação Completa (projeto/index.md) embute
  # projeto/modelagem.md (modelo de dados). base_path inclui docs/ → o caminho
  # do embed é relativo a docs/ (ex. "projeto/modelagem.md").
  - pymdownx.snippets:
      base_path: ["docs", "."]
      check_paths: true
  # Mermaid nativo do Material — não precisa de plugin extra
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

# nav por CICLO DE VIDA (constituição §2/§4): Resumo → Pré-projeto → Projeto →
# Operação → Dev → Público → Etapas → Decisões → Glossário. Mantenha só as seções
# que existem; descomente conforme criar o conteúdo. Resumo, Projeto (o livro) e
# Glossário já vêm ligados; o resto é esqueleto na ordem recomendada.
nav:
  - Resumo Executivo: index.md      # porta do diretor: problema + como resolve, sem jargão, → Documentação Completa (§2)
  - Mudanças: changelog.md          # embute o CHANGELOG.md da raiz (§1.8) — crie docs/changelog.md do templates/changelog.md
  # - Pré-projeto:                  # docs/pre-projeto/ — viabilidade/estudo de caso, ANTES de decidir construir (§4, nível 1)
  #     - Estudo de caso: pre-projeto/estudo-de-caso.md
  - Projeto:                        # a ESPECIFICAÇÃO — o desenho do sistema no estado atual
      - Documentação Completa: projeto/index.md   # o livro AUTORADO; embute projeto/modelagem.md via --8<-- (§2)
  #     - Requisitos / spec: projeto/requisitos.md
  # projeto/modelagem.md (modelo de dados) é embutido no livro — sem entrada própria.
  # - Operação:                     # docs/operacao/ — runbooks técnicos: deploy, recuperação (§4, nível 5)
  #     - Runbook Y: operacao/runbook-y.md
  # - Dev / API:                    # docs/dev/ — para quem mexe no código (§4, nível 4)
  #     - Guia do código: dev/guia-do-codigo.md   # narrativa autorada da organização do código (+ inventário, se houver passo Javadoc/dartdoc no docs.yml)
  #     - Mapa do código: dev/index.md            # linke a API gerada: [API Reference](api/index.html) — Markdown NORMAL (api/ é gerado em docs/dev/api/ ANTES do build → --strict valida; §5)
  # - Público:                      # docs/public/ — aberto (§5)
  #     - Visão geral: public/index.md
  #     - Manual:
  #         - Como fazer X: public/manual/como-fazer-x.md
  #     - API (contrato): public/api/index.md     # embute o OpenAPI via swagger-ui-tag
  # - Etapas do Projeto:            # docs/projeto/NN-*.md — a EXECUÇÃO: o delta de cada etapa ao longo do tempo. ≠ Projeto, que é a spec/desenho (§5)
  #     - 01 — Primeira etapa: projeto/01-primeira-etapa.md
  # - Decisões:
  #     - 0001 — Título da decisão: decisoes/0001-titulo-da-decisao.md
  - Glossário do projeto: glossario.md
