ADR-005: Markdown como Formato Único

Status: Aceito

Data: 2024-11-02

Decisores: Aron Cardoso

Contexto

O repositório filament-core-docs precisa de um formato para documentação que seja:

• Fácil de escrever e revisar
• Versionável via Git com diffs legíveis
• Compatível com ferramentas de geração de sites estáticos
• Não require ferramentas especializadas para leitura

Forças em jogo:

• Simplicidade: Baixa barreira de entrada para contribuidores
• Legibilidade: Deve ser legível tanto em texto puro quanto renderizado
• Tooling: Suporte amplo de editores e linters
• Portabilidade: Não deve depender de plataforma específica

Alternativas Consideradas

Opção 1: reStructuredText (rST)

• Prós:
  • Muito expressivo (suporta diretivas complexas)
  • Padrão do Python (Sphinx)
  • Semântica rica
• Contras:
  • Sintaxe mais complexa que Markdown
  • Menos popular (curva de aprendizado maior)
  • Tooling menos abundante

Opção 2: AsciiDoc

• Prós:
  • Muito poderoso (livros técnicos)
  • Suporta includes, macros, etc
  • Excelente para documentação complexa
• Contras:
  • Sintaxe verbosa
  • Menos popular que Markdown
  • Requer conversão para consumo

Opção 3: Markdown (Escolhida)

• Prós:
  • Extremamente simples de aprender
  • Universal (GitHub, GitLab, VSCode, etc)
  • Diffs Git muito legíveis
  • Suporte nativo em VitePress
  • Renderizado automático em GitHub
• Contras:
  • Menos expressivo que rST/AsciiDoc
  • Variações de sabores (CommonMark, GFM, etc)
  • Limitado para casos complexos

Opção 4: Hybrid (Markdown + WYSIWYG)

• Prós:
  • Edição visual para não-técnicos
  • Preview instantâneo
• Contras:
  • Diffs Git problemáticos
  • Vendor lock-in (Notion, GitBook, etc)
  • Perda de controle sobre formato

Decisão

Escolhemos Markdown puro (GitHub Flavored Markdown via CommonMark) com as seguintes regras:

1. Apenas arquivos .md:

   • Nenhum HTML inline (exceto casos extremos)
   • Nenhum código de produção
   • Apenas Markdown ilustrativo

2. Convenções de formatação:

   • ATX-style headings (#, ##, ###)
   • Code blocks com linguagem especificada
   • Linhas ~100 caracteres para facilitar review
   • Diagramas em text blocks (monospace)

3. Tooling obrigatório:

   • markdownlint para consistência
   • markdown-link-check para links
   • VitePress para renderização

4. Extensões permitidas:

   • Tables (GFM)
   • Task lists
   • Strikethrough
   • Autolinks
   • Footnotes (quando necessário)

5. Proibições:

   • Código de produção (PHP, JS, etc) executável
   • Binários ou imagens grandes (preferir diagramas texto)
   • HTML complexo (apenas tags simples quando essencial)

Consequências

Positivas

• Barreira de entrada zero: Qualquer desenvolvedor conhece Markdown
• Git-friendly: Diffs são legíveis e fáceis de revisar
• Portabilidade: Renderizado automaticamente em GitHub, VSCode, etc
• Tooling abundante: Linters, formatters, conversores
• VitePress-native: Zero configuração para renderização
• Busca eficiente: Texto puro indexa perfeitamente

Negativas

• Expressividade limitada: Não suporta casos muito complexos
• Inconsistências: Diferentes sabores de Markdown (mitigado por linter)
• Diagramas textuais: Menos visuais que Mermaid ou imagens
• Tabelas complexas: Difíceis de manter em Markdown puro

Neutras

• Necessita disciplina: Formatação deve ser consistente (mitigado por lint)
• Aprendizado de convenções: Contributors precisam seguir style guide

Notas de Implementação

Estrutura de Arquivos

docs/
├── contracts/
│   ├── overview.md          # ✅ Markdown puro
│   └── roadmap.md           # ✅ Markdown puro
├── snippets/
│   └── monorepo-architecture.md  # ✅ Diagrama em text block
└── adr/
    ├── 001-*.md             # ✅ ADR em Markdown
    └── template.md          # ✅ Template em Markdown

Exemplo de Code Block Correto

```php
// Exemplo ilustrativo (não código de produção)
class PersonCreated
{
    public function __construct(
        public readonly PersonDTO $person
    ) {}
}
```

Exemplo de Diagrama Textual

```text
filament-core-contracts
 ├─ filament-core-invoices
 ├─ filament-core-people
 └─ filament-core-communications
```

Lint Configuration

// .markdownlint.json
{
  "default": true,
  "MD013": false,  // Desabilita limite de linha rígido
  "MD033": {
    "allowed_elements": ["br", "details", "summary"]
  },
  "MD041": false  // Permite começar sem heading level 1
}

Quando Markdown NÃO é Suficiente

Casos onde precisaríamos alternativa (mas ainda não encontrados):

• Diagramas interativos muito complexos → Considerar Mermaid via VitePress
• Tabelas com 10+ colunas → Reavaliar estrutura do conteúdo
• Matemática complexa → VitePress suporta KaTeX se necessário

Referências

• CommonMark Spec
• GitHub Flavored Markdown
• Markdown Guide
• VitePress Markdown Extensions
• Diretrizes para Agentes - Convenções de escrita