Skill Markdown para mdsvr
Gere um conjunto de documentação Markdown completo, válido e com múltiplos arquivos para uso com mdsvr — suporta tanto modo servidor quanto exportação estática.
Quando esta skill for acionada, produza múltiplos arquivos .md que formem um site de documentação coeso,
seguindo estritamente todas as convenções do mdsvr.
Passo 1 — Entender a Solicitação
Antes de gerar arquivos, extraia da solicitação do usuário:
- Tópico / nome do produto — o que está sendo documentado?
- Público-alvo — desenvolvedores, usuários finais, equipes de operações, etc.
- Escopo — quantas páginas / seções são necessárias?
- Idioma — português, inglês ou bilíngue?
- Diagramas necessários? — se sim, leia
references/rules/mermaid.mdpara as regras de sintaxe.
Se algum desses itens não estiver claro, faça UMA pergunta focada antes de prosseguir.
Passo 2 — Planejar a Estrutura de Arquivos
Projete uma hierarquia lógica antes de escrever o conteúdo. Um site de documentação típico do mdsvr:
docs/
├── README.md ← Página inicial (obrigatório)
├── 01-primeiros-passos/
│ ├── README.md ← Índice da seção
│ ├── 01-instalacao.md
│ ├── 02-inicio-rapido.md
│ └── 03-configuracao.md
├── 02-guias/
│ ├── README.md
│ ├── 01-uso-basico.md
│ └── 02-avancado.md
├── 03-referencia-api/
│ ├── README.md
│ └── 01-endpoints.md
└── 04-solucao-de-problemas.md
Adapte a estrutura ao tópico do usuário. Aumente ou reduza a escala conforme necessário.
Passo 3 — Aplicar Regras de Arquivos e Links do mdsvr (OBRIGATÓRIO)
3.1 Regras de Nomenclatura de Arquivos
| Regra | ❌ Errado | ✅ Correto |
|---|---|---|
| Sem pontos no meio do nome | 0.1.inicio-rapido.md | 01-inicio-rapido.md |
| Sem pontos no meio do nome | config.v2.md | config-v2.md |
| Use kebab-case | PrimeirosPassos.md | primeiros-passos.md |
| Use prefixo numérico para ordenação | guia.md (na barra lateral) | 01-guia.md |
| Nomes descritivos | pagina1.md | instalacao.md |
| Índice do diretório deve ser | index.md | README.md |
3.2 Regras de Estrutura de Links
| Regra | ❌ Errado | ✅ Correto |
|---|---|---|
| Use apenas caminhos relativos | [Guia](/docs/guia) | [Guia](./guia) |
Sem extensão .md em links | [Setup](./setup.md) | [Setup](./setup) |
| Link para diretório, não para README | [Inicio](./01-primeiros-passos/README) | [Inicio](./01-primeiros-passos) |
| Links de âncora devem corresponder aos cabeçalhos | [Veja](#passos-de-instal) (se o cabeçalho não existir) | Corresponder exatamente |
3.3 Regras de Estrutura de Cabeçalhos
| Regra | ❌ Errado | ✅ Correto |
|---|---|---|
| Toda página precisa de H1 | (página começa com H2) | # Título da Página como primeiro cabeçalho |
| Não pule níveis de cabeçalho | H1 → H3 | H1 → H2 → H3 |
| Cabeçalhos devem ser descritivos | ## Seção 1 | ## Requisitos de Instalação |
Passo 4 — Aplicar Frontmatter em Todos os Arquivos
Cada arquivo .md deve incluir frontmatter YAML para SEO e metadados do mdsvr:
---
title: "Título da Página"
description: "Descrição de uma frase do conteúdo desta página."
---
Passo 5 — Diretrizes de Conteúdo
README.md (Página Inicial) — Obrigatório
- Deve existir na raiz da pasta de documentação.
- Incluir: visão geral do projeto, links de navegação rápida para todas as seções.
- Use um destaque de boas-vindas se apropriado.
README.md da Seção (Índice do Diretório)
- Resuma o que a seção cobre.
- Liste todas as páginas da seção com links relativos.
Páginas de Conteúdo
- Um tópico focado por página.
- Comece com um breve parágrafo introdutório.
- Use componentes MDX quando apropriado:
:::note,:::warning,:::tip,:::dangerpara destaques.- Listas numeradas para procedimentos passo a passo.
- Faça links livremente para páginas relacionadas usando caminhos relativos.
- Termine com uma seção "Próximos Passos" ou "Relacionados" quando for útil.
Passo 6 — Diagramas Mermaid (Quando Necessário)
Se a documentação se beneficiar de diagramas (arquitetura, fluxos, sequências, DERs,
máquinas de estado, etc.), incorpore diagramas Mermaid inline nos arquivos .md relevantes.
Antes de gerar qualquer diagrama, leia
references/rules/mermaid.mdpara a referência completa de sintaxe e regras de geração. Todas as regras desse arquivo são obrigatórias.
Lista de verificação rápida (do mermaid.md):
- Escolha o tipo de diagrama mais apropriado — NÃO use
flowchartpor padrão. - Sempre declare a direção em fluxogramas:
flowchart TDouflowchart LR. - IDs dos nós: apenas letras, números e sublinhados. Sem
-,.,(,). - Rótulos de nós com espaços devem usar aspas duplas:
A["Meu Rótulo"]. - Subgrafos devem ter IDs explícitos:
subgraph meu_id["Rótulo"]. - Diagramas de sequência: declare todas as linhas
participantantes das mensagens. - Sem cores ou estilos codificados, a menos que o usuário solicite explicitamente.
- Use emoji em vez de cores para transmitir significado semântico.
- Um diagrama por bloco de código; valide a sintaxe antes de produzir.
Passo 7 — Criar Arquivos e Entregar
Use create_file para escrever cada arquivo .md no sistema de arquivos. Em seguida, compacte tudo
em ZIP e chame present_files para que o usuário possa baixar o resultado.
7.1 Escrever cada arquivo
Para cada arquivo na estrutura planejada, chame create_file com o caminho completo
em /mnt/user-data/outputs/<nome-do-projeto>/:
/mnt/user-data/outputs/meu-projeto/README.md
/mnt/user-data/outputs/meu-projeto/01-primeiros-passos/README.md
/mnt/user-data/outputs/meu-projeto/01-primeiros-passos/01-instalacao.md
...
Escreva o conteúdo final completo em cada chamada — não escreva placeholders.
7.2 Compactar em ZIP e apresentar
Após todos os arquivos serem escritos, compacte a pasta de saída e chame present_files:
cd /mnt/user-data/outputs
zip -r meu-projeto-docs.zip meu-projeto/
Em seguida, chame present_files com o caminho para o arquivo .zip.
7.3 Resumo no chat
Após present_files, escreva uma mensagem curta no chat contendo:
- Árvore de arquivos — mostre a estrutura completa de diretórios gerada.
- Como servir — comando único:
npx mdsvr ./meu-projetooumdsvr ./meu-projeto. - Contagem de páginas — ex.: "8 páginas geradas em 3 seções."
Referência Rápida — Erros Comuns a Evitar
❌ Caminho absoluto em link: [Página](/docs/pagina)
✅ Caminho relativo: [Página](./pagina)
❌ Extensão .md em link: [Página](./pagina.md)
✅ Sem extensão: [Página](./pagina)
❌ Link para arquivo README: [Seção](./01-secao/README)
✅ Link para diretório: [Seção](./01-secao)
❌ Ponto no nome do arquivo: 01.inicio-rapido.md
✅ Hífen como separador: 01-inicio-rapido.md
❌ Faltando H1: ## Introdução (primeiro cabeçalho é H2)
✅ Comece com H1: # Introdução
❌ Nível de cabeçalho pulado: # Título → ### Sub (pula H2)
✅ Hierarquia adequada: # Título → ## Seção → ### Subseção
❌ Sem frontmatter: (arquivo começa diretamente com #)
✅ Frontmatter presente: --- title: "..." description: "..." ---
Arquivos de Referência
references/rules/mermaid.md— Referência completa de sintaxe Mermaid v11 para todos os 19 tipos de diagrama. Leia este arquivo sempre que algum diagrama for necessário na documentação.