Escrita com Markdown e Mermaid

Visão Geral

Esta habilidade fornece um estilo de casa opcional para documentação Markdown com diagramas estruturais Mermaid. Siga o formato de saída solicitado, as convenções do repositório existente e os requisitos do periódico primeiro. Esta habilidade não substitui a análise científica ou a plotagem.

Um relacionamento expresso como Mermaid dentro de um arquivo .md é texto editável que difere de forma limpa no git. Um host compatível o renderiza sem uma etapa de compilação de usuário separada. Ele renderiza onde o host tem suporte a Mermaid; visualizadores Markdown simples podem mostrar apenas o código, e plataformas/extensões enviam diferentes versões do Mermaid. Ele usa uma representação de origem compacta, embora o uso de tokens dependa do diagrama. A exportação de SVG/PNG requer um renderizador; retenha a origem do diagrama ao lado das figuras exportadas.

"Quanto mais você tiver seus relatórios e arquivos em .md em texto puro, que é o que o mermaid é, além de ser uma linguagem de 'script' simples. Isso apenas ajuda em qualquer renderização downstream e especialmente em imagens geradas por IA (usando mermaid em vez de apenas texto longo para descrever relacionamentos < tokens). Adicionalmente, o mermaid pode renderizar junto com o markdown para uso fácil em quase qualquer lugar por humanos ou IA."

— Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19

Quando Usar Esta Habilidade

Use esta habilidade quando:

• Escrever um relatório Markdown solicitado, README, visão geral de métodos ou nota de pesquisa
• Diagramar um fluxo de trabalho, pipeline de dados, esquema, máquina de estados ou relacionamento conceitual
• Manter fontes Mermaid editáveis e suas exportações SVG/PNG renderizadas

Use ferramentas de plotagem científica diretamente para dados medidos, incerteza, gráficos estatísticos, geometria exata ou figuras de publicação que o Mermaid não pode representar fielmente. O Mermaid não é um precursor obrigatório para um gráfico quantitativo ou um ativo existente nativo de SVG/código.

🎨 A Filosofia do Formato de Origem

Por que diagramas baseados em texto vencem

O fluxo de trabalho de três fases

flowchart LR
    accTitle: Three-Phase Documentation Workflow
    accDescr: Markdown holds the structural diagram source. Quantitative charts come from data and plotting code; optional illustrations require a separate factual review.

    p1["📄 Phase 1<br/>Mermaid in Markdown<br/>(structural source)"]
    p2["🐍 Phase 2<br/>Python Generated<br/>(optional — data charts)"]
    p3["🎨 Phase 3<br/>AI Generated Visuals<br/>(optional — polish)"]
    out["📊 Final Deliverable"]

    p1 --> out
    data["Data and plotting code"] --> p2
    p1 -.->|"when needed"| p3
    p2 --> out
    p3 --> out

    classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class p1 required
    class p2,p3 optional
    class out output

Mantenha o Mermaid para diagramas estruturais e dados/código para gráficos quantitativos. Uma ilustração de IA não é uma conversão quantitativa; verifique cada rótulo e relacionamento em relação às suas fontes.

O que o Mermaid pode expressar

Esta habilidade inclui guias de 23 tipos de diagramas mais um guia de composição. O Mermaid suporta tipos adicionais; estas referências são um subconjunto curado, não um catálogo exaustivo de versões:

…