📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Guia de Markdown. Recomendado revisar antes de começar.

📝 Living Styleguide com Markdown Avançado & Mermaid

v1.0 — Docs-as-Code, GitHub Flavored Markdown (GFM), Diagramas Mermaid e Arquitetura Visual

Trilha de Especialização Pedagógica — Projeto 1 de 4

🎓 Nível Profissional Simulado: Technical Writer / Engenheiro de Software. Documentação técnica de excelência não fica em arquivos Word ou PDFs perdidos. Empresas globais adotam a filosofia Docs-as-Code: documentação escrita em Markdown, versionada no Git e com diagramas de fluxo gerados por código com Mermaid.

🎯 Objetivo & Escopo do Projeto

Construir o Living Styleguide de Documentação Técnica do portal, definindo padrões de formatação em GitHub Flavored Markdown (GFM), blocos de alertas semânticos (> [!NOTE], > [!IMPORTANT], > [!TIP]), tabelas estruturadas e diagramas visuais de arquitetura codificados em Mermaid.

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Gerente de Engenharia de Documentação)

“Nossos manuais e documentações técnicas estão desorganizados, com imagens de diagramas desatualizadas que ninguém consegue editar. Precisamos de um padrão de documentação ‘Docs-as-Code’: um guia de estilo em Markdown com tabelas, blocos de código com destaque sintático, alertas visuais coloridos e diagramas de arquitetura desenhados em texto com Mermaid que possam ser versionados pelo Git.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

ID Tipo Descrição Origem no Briefing
RF01 Funcional Definir convenção tipográfica de títulos, listas e blocos de código em Markdown. “guia de estilo em Markdown”
RF02 Funcional Implementar alertas semânticos padronizados do GitHub ([!NOTE], [!TIP], [!WARNING]). “alertas visuais coloridos”
RF03 Funcional Modelar fluxogramas e diagramas de sequência de sistemas utilizando sintaxe Mermaid. “diagramas desenhados em texto com Mermaid”
RNF01 Não-Funcional 100% renderizável nativamente no GitHub Pages e no parser Kramdown. Compatibilidade Web
RNF02 Não-Funcional Diagramas leves sem dependência de imagens binárias pesadas (.png/.jpg). Performance de Repositório

📋 Fase 2 — Backlog & User Stories

ID User Story Prioridade
US01 Como desenvolvedor, quero editar um diagrama de fluxo alterando apenas 3 linhas de texto em Mermaid. Alta
US02 Como leitor, quero visualizar alertas de segurança com cores destacadas para evitar erros de deploy. Alta

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Setup)

# Branch da funcionalidade
git checkout -b feature/US01-living-styleguide-mermaid

# Validar sintaxe Markdown com linter
npx markdownlint-cli index.md

🛠️ Fase 4 — Implementação Guiada de Diagramas Mermaid

graph TD
    A["👤 Cliente Web / Mobile"] -->|"Requisição HTTP"| B["🛡️ Nginx Proxy Reverso"]
    B -->|"Encaminha Carga"| C["⚙️ Backend Cluster (Go / Java)"]
    C -->|"Consulta SQL"| D[("🐘 PostgreSQL 16")]
    C -->|"Cache em Memória"| E[("⚡ Redis Cluster")]

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No seu editor/IDE, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd docs_01_styleguide_markdown_mermaid

2. Execute a aplicação ou testes

# Executar comandos específicos da tecnologia:
python main.py # ou npm run dev / ./gradlew build

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta navegar até a pasta antes de executar: cd catalogo_projetos/docs_01_styleguide_markdown_mermaid`

🧭 Decisões de Arquitetura (ADRs)

🧪 Testes de Validação & Asserções

🏛️ Arquitetura Visual & Engenharia do Sistema

O diagrama abaixo sintetiza a organização dos artefatos, contratos e diretrizes arquiteturais na subpasta docs/:

Arquitetura da Aplicação

flowchart TD
    subgraph Especificacao["Especificação & Contratos"]
        E1["Contratos Formais"] --> E2["Modelagem de Domínio"]
    end
    subgraph Implementacao["Implementação & Stacks"]
        I1["Arquiteturas & Código"] --> I2["Paridade Multilinguagem"]
    end
    subgraph Padroes["Governança & Padrões"]
        P1["Living Styleguides"] --> P2["Conformidade de Design"]
    end
    subgraph Homologacao["Qualidade & Homologação"]
        Q1["Matriz de Rastreabilidade"] --> Q2["Checkpoints CP-01..05 PASS"]
    end

    Especificacao --> Implementacao
    Implementacao --> Padroes
    Padroes --> Homologacao

    style Especificacao fill:#e3f2fd,stroke:#1976d2,stroke-width:1.5px
    style Implementacao fill:#fffde7,stroke:#fbc02d,stroke-width:1.5px
    style Padroes fill:#e8f5e9,stroke:#388e3c,stroke-width:1.5px
    style Homologacao fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px

🎯 Engenharia de Requisitos & Modelagem Formal

👤 User Stories (Histórias de Usuário)

ID Persona História de Usuário Critério de Aceite Prioridade
US-01 Redator Técnico / Arquiteto Desejo guia de estilo vivo com Markdown avançado, tabelas e callouts Padronização visual de documentação técnica para projetos de engenharia Alta
US-02 Engenheiro de Software Desejo biblioteca de diagramas Mermaid (Flowchart, Sequence, State, Class, ERD) Exemplos prontos e testados de todas as tipologias de diagramas suportadas Alta
US-03 Desenvolvedor Frontend Desejo diretrizes de acessibilidade e contraste para gráficos e diagramas Cores com taxa de contraste WCAG AA e compatibilidade com modo escuro/claro Alta
US-04 Tech Writer Desejo boas práticas para alertas, badges semânticos e blocos de código isolados Diretrizes de encapsulamento com as tags raw/endraw do Liquid, prevenindo colisões no Jekyll Média
US-05 Auditor de Documentação Desejo validação automática de sintaxe Markdown e compilação do Mermaid Verificação estática assegurando ausência de links quebrados e erros de parser Média

⚙️ Requisitos Funcionais (RF)

ID Descrição do Requisito Criticidade
RF-01 Living Styleguide documentando tipografia, tabelas, blocos de código e alertas Alta
RF-02 Galeria de 6 tipos de diagramas Mermaid com sintaxe canônica comentada Alta
RF-03 Padrão de isolamento estrito contra tags Liquid com blocos raw/endraw Alta
RF-04 Guia de nomenclatura de arquivos, semântica Git e arquitetura instrucional Média
RF-05 Scripts de linting de Markdown e validação de âncoras internas Média

🛡️ Requisitos Não-Funcionais (RNF)

ID Especificação Arquitetural Criticidade
RNF-01 100% de compatibilidade com o motor Kramdown do Jekyll e GitHub Flavored Markdown Alta
RNF-02 Aderência rigorosa às regras de acessibilidade e visualização responsiva Alta
RNF-03 Carregamento imediato sem dependências de frameworks JavaScript pesados Média
RNF-04 Isolamento dos artefatos na pasta docs/ Alta
RNF-05 Manutenibilidade e consistência em todo o portal educacional Alta

🔗 Matriz de Rastreabilidade (RTM)

User Story Requisito Funcional Requisito Não-Funcional Módulo / Artefato de Código Status de Homologação
US-01 RF-01 RNF-01, RNF-04 docs/arquitetura.md Testado
US-02 RF-02 RNF-01, RNF-02 docs/arquitetura.md Testado
US-03 RF-03 RNF-01, RNF-02 docs/arquitetura.md Testado
US-04 RF-04 RNF-01, RNF-05 docs/arquitetura.md Testado
US-05 RF-05 RNF-01, RNF-05 docs/check_markdown.py Testado

🏁 Checkpoints de Qualidade & Homologação

Checkpoint Escopo da Validação Artefato Verificado Status
CP-01 Estruturação de Contratos & Pastas docs/ PASS ✅
CP-02 Modelagem de Domínio & Schemas Domain Schemas PASS ✅
CP-03 Paridade Técnica & Implementações Multi-stack Code PASS ✅
CP-04 Documentação Viva & Estilo Styleguide & Guides PASS ✅
CP-05 Homologação com RTM & Validações Quality Gate PASS ✅