📚 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 proj_aplicacoes_full_stack/projetos/docs_01_styleguide_markdown_mermaid`

🧭 Decisões de Arquitetura (ADRs)

—`

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

—`

✅ Checkpoint Final

  1. Guia de estilo de documentação publicado e navegável.
  2. Diagramas Mermaid integrados ao ecossistema Jekyll.
⬅️ Ver Todos os Projetos no Super-Hub 🏠 Página Inicial do Portal