| name | validate-docs-rendered |
| description | Validate that docs RENDER correctly — Mermaid parseable, internal links resolve, YAML frontmatter consistent, code blocks have language. Triggers: "validar renderizacao", "verificar diagramas", "checar links". Complements validate-documentation (textual) and analyze (cross-artifact). |
CSTK Adaptation
Adapted from JotJunior/cstk skill validate-docs-rendered at commit 35922cf.
Use this as a Codex skill; follow local repository instructions and Codex tool names when source text mentions Claude-specific commands or slash commands.
Skill: Validar Renderizacao de Documentacao
Esta skill e uma skill de verificacao de produto (categoria 2 do artigo
original). Ela nao valida se a documentacao esta escrita corretamente — isso e
responsabilidade de validate-documentation e analyze. Ela valida se a
documentacao realmente funciona quando renderizada em GitHub, GitLab,
viewers Markdown, ou outros consumidores downstream.
O gap que ela fecha e o mesmo que o artigo cita: "a diferenca entre doc que
passa no review e doc que renderiza corretamente em producao e onde moram os
bugs mais caros".
Pre-requisitos
Obrigatorio: diretorio com documentacao Markdown existente (tipicamente
docs/). Se argumento vazio, assume docs/ como default.
Proximos passos
- Corrigir issues reportados (diagramas invalidos, links quebrados)
- Re-rodar a skill para confirmar zero issues
- Considerar rodar como hook pre-commit para prevenir regressao
FLUXO DE EXECUCAO
1. LOCALIZAR Descobrir escopo (arquivo unico ou arvore)
|
2. VALIDAR Rodar scripts de validacao em paralelo
|
3. CLASSIFICAR Agrupar findings por severidade
|
4. REPORTAR Output tabular + exit code
ETAPA 1: LOCALIZAR
Determinar o escopo a partir de the user's request:
- Caminho para arquivo (ex:
docs/foo.md): validar apenas esse arquivo
- Caminho para diretorio (ex:
docs/02-requisitos-casos-uso/): validar recursivamente
- Vazio: assumir
docs/ na raiz do projeto
Se o caminho nao existe, abortar com mensagem clara.
ETAPA 2: VALIDAR
Usar o script scripts/validate.sh (mesmo diretorio desta skill). O script
executa 4 validacoes em paralelo onde possivel:
2.1 Diagramas Mermaid
Verifica sintaxe de blocos ```mermaid:
- Participantes declarados antes de uso em
sequenceDiagram
- Setas validas (
->>, -->>, ->, -->, etc.)
- Nos com IDs unicos em
flowchart/graph
- Fechamento correto de
alt/else/end, loop/end, par/end
- Sintaxe de
erDiagram (relacionamentos, cardinalidade)
Severidade: ERRO (quebra renderizacao).
2.2 Links internos
Verifica links [texto](path/relativo.md) e [texto](./foo.md#anchor):
- Arquivo apontado existe
- Anchor (
#secao) corresponde a um header existente (normalizado via slug)
- Links absolutos comecando com
/ resolvidos contra raiz do repo
Severidade: ERRO para quebrados, AVISO para anchors case-sensitive
inconsistentes.
2.3 Code blocks sem linguagem
Verifica ``` sem linguagem declarada (reduz syntax highlighting):
- Todo fence de 3 backticks deve ter linguagem (ex:
bash, python, md)
- Excecao: code blocks inline ou explicitamente marcados como
text/plain
Severidade: AVISO.
2.4 Frontmatter YAML
Para arquivos que comecam com ---:
- Frontmatter fecha com
--- em linha proxima
- Campos obrigatorios do projeto (ex:
name, description em skills) presentes
- YAML parseavel (sem indentacao inconsistente, strings nao-escapadas)
Severidade: ERRO se malformado.
2.5 Tabelas Markdown malformadas
- Header tem linha separadora (
| --- |)
- Numero de colunas consistente entre linhas
Severidade: AVISO.
ETAPA 3: CLASSIFICAR
| Severidade | Criterio | Impacto |
|---|
| ERRO | Quebra renderizacao no GitHub/viewer | Bloqueia merge / viewer mostra fallback ruim |
| AVISO | Renderiza mas sub-otimo | Afeta legibilidade mas nao quebra |
| INFO | Sugestao de melhoria | Opcional |
ETAPA 4: REPORTAR
Output em formato tabular:
## Rendering Validation Report
**Escopo**: [path validado]
**Arquivos analisados**: [N]
### Resumo
| Severidade | Quantidade |
|------------|------------|
| ERRO | [N] |
| AVISO | [N] |
| INFO | [N] |
### Findings
| Arquivo | Linha | Severidade | Tipo | Mensagem |
|---------|-------|------------|------|----------|
| docs/foo.md | 42 | ERRO | Mermaid | participant `Usuario` nao declarado antes de uso |
| docs/bar.md | 15 | ERRO | Link | Arquivo nao encontrado: `../baz.md` |
| docs/baz.md | 88 | AVISO | CodeBlock | Fence sem linguagem declarada |
### Proximos Passos
- Corrigir ERROs antes de commitar
- AVISOs podem ser agendados para proximo cleanup
- Re-rodar esta skill para confirmar fix
Exit code: 0 se zero ERROs, 1 se houver ERROs (para uso em hook/CI).
Gotchas
Esta skill NAO substitui validate-documentation nem analyze
validate-documentation: valida estrutura textual de um documento (secoes obrigatorias, minimos de conteudo)analyze: valida consistencia cross-artifact (spec vs plan vs tasks)validate-docs-rendered: valida que a documentacao renderiza corretamente quando consumida
As tres sao complementares — rodar todas num fluxo de quality gate.
Validacao de Mermaid e heuristica, nao renderer real
Sem um renderer Mermaid de verdade (mmdc, kroki), a validacao se baseia em
regex e regras sintaticas. Captura a maioria dos erros mas pode deixar passar
edge cases. Para validacao 100%, considerar integrar com @mermaid-js/mermaid-cli
no pipeline CI.
Links case-sensitive em GitHub mas case-insensitive em macOS
Um link [x](./Foo.md) funciona em macOS (filesystem case-insensitive por
default) mas quebra em Linux/GitHub. A validacao trata essa discrepancia como
AVISO, nao ERRO — ajustar para ERRO se o time roda Linux exclusivamente.
Code blocks em Markdown aninhados
Quando um arquivo .md documenta sintaxe Markdown, os fences aninhados podem
confundir a validacao. A skill escapa isso detectando ~~~ como delimitador
alternativo ou ignorando blocks dentro de heredocs.
Anchors do GitHub seguem regra especifica
O slug de um header em GitHub e: lowercase, - no lugar de espacos, remocao
de pontuacao. Mas GitLab e MkDocs tem regras ligeiramente diferentes. A skill
valida contra a regra do GitHub por padrao — configurar em config.json se
o consumidor principal e outro.
Rodar em CI e valioso — local como pre-commit e rapido demais
Esta skill e rapida (segundos para arvores pequenas) mas ainda assim,
rodar a validacao completa em cada commit pode irritar. Consideracoes:
- Local (pre-commit): validar so arquivos alterados
- CI (PR checks): validar arvore completa
- Scheduled: rodar em main periodicamente para detectar link rot externo
Source License
This skill includes material adapted from JotJunior/cstk, licensed under MIT. The copyright and permission notice are included in references/cstk-license.md.
