Pular para conteúdo

🧭 CONTEXTO DO PROJETO — Ecossistema portal_mkdocs

Documento de Contexto Técnico e Arquitetural para Desenvolvedores e Agentes de IA. Atualizado em Setembro de 2026.

1. Identificação do Projeto

  • Nome: Ecossistema Educacional Multirepo portal_mkdocs
  • Autor / Mantenedor: Ricardo Tec Pro (ricardotecpro)
  • Organização / Domínio: https://ricardotecpro.github.io/
  • Diretório Raiz Local: D:\SourceCode\GitRepos\github.io\portal_mkdocs
  • Ambiente de Execução: Windows 10/11, PowerShell, Python 3.11+

2. Topologia Multirepo (Raiz Plana)

O projeto migrou de uma arquitetura legada com subpastas aninhadas para uma Raiz Plana composta por exatamente 51 repositórios Git independentes:

  1. portal_mkdocs_hub: Portal Central agregador de cursos, trilhas, catálogo e governança.
  2. ads_mod_01 a ads_mod_14 (14 repositórios): Módulos Nucleares de Análise e Desenvolvimento de Sistemas.
  3. ads_spec_* (26 repositórios): Especializações técnicas em linguagens, frameworks, cloud, IA e segurança.
  4. ads_proj_* (2 repositórios): Projetos integradores práticos e capstone.
  5. ads_sistemas_embarcados (1 repositório): IoT, Arduino, ESP32 e microcontroladores.
  6. adm_gestao_* (2 repositórios): Gestão de processos (BPMN/DMN) e Governança de TI (ITIL/TIAA).
  7. ads_extra_* (6 repositórios): Guias de ferramentas, Markdown, UML, Hardware, Redes e Power BI.

3. Stack Tecnológica e Ferramentas Homologadas

Camada Tecnologia Versão Função no Ecossistema
SSG MkDocs 1.6.1 Gerador de documentação estática
Tema Base Material for MkDocs 9.7.7 Interface responsiva, navegação em abas, busca instantânea
Tags material/tags Nativo Classificação didática cruzada por tecnologia (tags.md)
Impressão / PDF mkdocs-print-site-plugin 2.6.0+ Compilação da apostila consolidada A4 em /print_page/
Datas Git mkdocs-git-revision-date-localized-plugin 1.3.0+ Histórico de modificação de páginas (com paralelismo ativo)
Slides Reveal.js 4.x Motor de slides técnicos interativos em docs/slides/
Quizzes Custom quiz.js + quiz.css 1.0 Mecanismo autônomo de avaliação com 10 questões interativas
Diagramas Mermaid.js 11.12.3 Diagramação declarativa (fluxogramas, ER, sequências, timeline)
Matemática MathJax 3.x Renderização de fórmulas matemáticas e expressões formais
Terminal Termynal.js Custom Simulações de comandos de terminal com digitação animada

4. Estrutura Padrão de um Curso (ads_mod_* / ads_spec_*)

Cada repositório de curso possui a seguinte árvore estrita de diretórios e arquivos:

ads_mod_XX_nome_do_curso/
├── .git/                          # Repositório Git autônomo (branch main e gh-pages)
├── .github/workflows/deploy.yml   # Workflow manual (workflow_dispatch + pip cache)
├── mkdocs.yml                     # Configuração SSG, plugins, tema, paleta e navegação
├── docs/
│   ├── index.md                   # Home page do curso com cards de acesso
│   ├── plano.md (ou index.md)     # Plano de ensino completo de 20 unidades
│   ├── tags.md                    # Catálogo temático (<!-- material/tags -->)
│   ├── sobre.md                   # Metadados do curso e metodologia
│   ├── materiais.md               # Links e recursos complementares
│   ├── project_roadmap.md         # Cronograma e roadmap das aulas
│   ├── print_page.md              # Rota para e-book consolidado para impressão
│   ├── aulas/                     # 20 aulas: aula-01.md a aula-20.md
│   ├── exercicios/                # 20 exercícios com gabarito: exercicio-01.md a exercicio-20.md
│   ├── projetos/                  # 20 projetos aplicados: projeto-01.md a projeto-20.md
│   ├── quizzes/                   # 20 quizzes interativos: quiz-01.md a quiz-20.md
│   ├── slides/                    # 20 slides Reveal.js: slide-01.md a slide-20.md
│   ├── setups/                    # 5 a 6 setups técnicos: setup-01.md a setup-06.md
│   └── assets/
│       ├── css/ (extra.css, quiz.css, home.css)
│       ├── js/ (quiz.js, mathjax.js, termynal.js)
│       └── images/ (logo.svg, favicon)
└── overrides/                     # Customizações do tema Material (main.html, home.html)

5. Protocolo de Deploy e Gestão de Custos de CI/CD

  • Problema Histórico: A cada commit com 51 repositórios, acionavam-se 51 pipelines do GitHub Actions, esgotando a cota mensal gratuita de minutos em menos de 1 hora.
  • Solução Padronizada:
  • Workflows .github/workflows/deploy.yml configurados exclusivamente com on: workflow_dispatch (acionamento sob demanda).
  • Todos os commits nos repositórios remotos levam o sufixo [skip ci].
  • Publicação automatizada via CLI local através de python multirepo.py deploy <repo> ou deploy --all --yes, executando mkdocs gh-deploy --force --ignore-version.
  • Resultado: 100% de disponibilidade no GitHub Pages com 0 minutos consumidos no GitHub Actions.

6. Pre-Commit Hooks e Linters de Governança

  • Pre-Commit Hook (.git/hooks/pre-commit):
  • Instalado em lote nos 51 repositórios por python multirepo.py install-hooks.
  • Valida integridade antes de qualquer commit:
    • Impede staged de pastas proibidas (_analisar_deletar, site/, .cache/).
    • Bloqueia links de slides quebrados com prefixo relativo incorreto (../slide-).
    • Intercepta textos placeholders ("Breve explicação sobre", "Exercício 1...").
    • Rejeita projetos com conteúdo raso (< 50 palavras) ou reticências vazias (...).
  • Linter de Sintaxe Markdown (python multirepo.py lint-markdown):
  • Varredura paralela multithread em todos os 8.455 arquivos .md.
  • Valida fechamento de blocos de código (fences ```), frontmatter YAML, cabeçalhos # Título e sintaxe de links/admonitions.\n