🎨 Plano de Migração de Tema: Cayman → Minimal Mistakes

Substituição do tema Jekyll do portal, com testes de paridade, critérios de aceite por fase e plano de rollback

💡 Objetivo: Substituir o tema pages-themes/cayman (landing page de projeto único, sem navegação hierárquica) pelo minimal-mistakes-jekyll, resolvendo os problemas estruturais de UI/UX identificados na auditoria de 2026-08-31/09-01 — sem perder nenhum recurso já construído (Mermaid, MathJax, alertas GitHub, quizzes, admonitions, cards, botões, code blocks) e sem quebrar as ~4.000 páginas do portal em produção.

📊 1. Contexto e decisão

1.1 Problema diagnosticado no tema atual (Cayman)

1.2 Candidatos avaliados

Decisão: Minimal Mistakes. Motivo decisivo: testado o comportamento real do aluno (entra, escolhe 1 curso, fica alternando capítulos, raramente troca de curso) — o nav_fold do Just the Docs reseta a sidebar a cada página de capítulo (confirmado ao vivo clicando em “Próximo Capítulo”), errando exatamente na ação mais repetida. O Minimal Mistakes, com um JS de auto-colapso por URL (não por estado salvo), acerta essa ação em 100% dos casos, e seus 3 bugs de compatibilidade são todos superficiais (CSS, string de tradução, ordem de DOM) — já resolvidos e testados no laboratório.

Ver detalhamento completo da investigação na memória de sessão do agente (não versionada no repo): comparação de 6 configurações de tema, testes em 3 tamanhos de tela, bateria de paridade de recursos.

🗺️ 2. Escopo

• 40 módulos (mod_XX_*, spec_*, extra_*, proj_*), a maioria já no “Padrão Ouro” de 20 capítulos × 5 categorias (topicos, exercicios, exemplos, quizzes, slides) = até 100 arquivos por módulo. ⚠️ Número contado por listagem de diretório em 2026-09-01 — não é estático: há sessões paralelas criando módulos novos ativamente (extra_guia_de_linguagens_de_programacao apareceu entre duas contagens no mesmo dia). Reconferir com ls -d mod_* spec_* extra_* proj_* imediatamente antes de gerar o _data/navigation.yml na Fase 0, não confiar neste número congelado no documento.
• Estimativa: ~3.800 a 4.000 arquivos .md no total.
• Fora de escopo desta migração: conteúdo dos capítulos (não muda uma linha de texto didático); apenas front matter, layout, tema e a camada de JS/CSS de apresentação.

🏗️ 3. O que muda tecnicamente

3.1 _config.yml e Gemfile

# Gemfile
gem "minimal-mistakes-jekyll", "~> 4.26"
gem "jekyll-include-cache"

# _config.yml
theme: minimal-mistakes-jekyll
minimal_mistakes_skin: "dark"    # ou o skin escolhido — decisão de design separada
locale: "pt-BR"
defaults:
  - scope: { path: "", type: "pages" }
    values: { layout: single, author_profile: false, toc: true, toc_sticky: true }

_layouts/ e _includes/head-custom.html (Cayman) são removidos — o tema passa a fornecer os próprios. Toda a customização sobrevive em um único arquivo novo: _includes/head/custom.html (hook oficial do Minimal Mistakes).

3.2 Sidebar escalável por curso (o maior item de engenharia novo)

Cada um dos 40 módulos vira uma entrada de topo em _data/navigation.yml, com seus capítulos aninhados. Um script gera esse arquivo a partir dos topicos/index.md de cada módulo (mesma fonte da verdade já usada pelos índices do site hoje).

JS (_includes/head/custom.html) detecta o curso atual pela URL e colapsa todos os outros — testado e funcionando com 4 cursos simulados; precisa reteste de performance com os 40 reais antes do rollout completo (ver §6, Risco R1).

3.3 Inventário completo de correções a portar

3.4 Front matter — mudança em massa (o item mecânico mais volumoso)

Todo arquivo de conteúdo precisa trocar layout: default → layout: single + sidebar: {nav: "<slug-do-modulo>"}. Achado da rodada de testes: isso vale para todos os tipos de arquivo (topicos, exercicios, exemplos, quizzes — não descobri necessidade em slides, que usa layout próprio e fica fora desta migração por ora). Script único, idempotente, roda sobre os 40 módulos de uma vez.

🚦 4. Fases de execução

flowchart TD
    F0["Fase 0: Preparação\nScripts de migração + geração de navigation.yml"]
    F1["Fase 1: Piloto (1 módulo)\nmod_11 em branch isolada, site atual intacto"]
    F2["Fase 2: Validação do piloto\nBateria de testes completa (Seção 5)"]
    F3["Fase 3: Rollout gradual\n+5-10 módulos por lote, gate a cada lote"]
    F4["Fase 4: Rollout completo\n40/40 módulos + corte do Cayman"]
    F5["Fase 5: Estabilização\nMonitorar CI/analytics por 1-2 semanas"]

    F0 --> F1 --> F2 -->|passou nos critérios de aceite| F3 --> F4 --> F5
    F2 -.->|falhou| ROLLBACK["Rollback (Seção 7)"]
    F3 -.->|falhou em algum lote| ROLLBACK

    style F0 fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px
    style F1 fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style F2 fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style F3 fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style F4 fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style F5 fill:#ede7f6,stroke:#7e57c2,stroke-width:2px
    style ROLLBACK fill:#ffebee,stroke:#f44336,stroke-width:2px

Fase 0 — Preparação (sem tocar no site em produção)

1. Criar branch theme/minimal-mistakes.
2. Script gerar_navigation_yml.py: lê mod_XX/topicos/index.md de cada módulo, gera a entrada correspondente em _data/navigation.yml.
3. Script migrar_front_matter.py: aplica layout: single + sidebar + remove H1 duplicado, com flag --modulo para rodar em 1 módulo por vez (obrigatório na Fase 1) ou --todos (só na Fase 3+).
4. Montar _includes/head/custom.html definitivo com os 15 itens da tabela §3.3.
5. Copiar _data/ui-text.yml (bloco pt-BR: corrigido).

Fase 1 — Piloto em 1 módulo

• Rodar os scripts só em mod_11_qualidade_e_testes_de_software (já é o módulo mais testado nesta investigação).
• Site de produção permanece 100% no Cayman — a mudança de tema é _config.yml, então não dá pra ter os dois ao mesmo tempo em produção; o piloto roda em preview local/branch, não em deploy real, até passar na Fase 2.

Fase 2 — Validação (gate obrigatório antes de prosseguir)

Ver bateria completa na Seção 5. Só avança para a Fase 3 se 100% dos itens passarem.

Fase 3 — Rollout gradual — ✅ CONCLUÍDA 2026-09-01

Executada em 4 lotes de ~10 módulos, cada um com dry-run + git diff --stat revisado (uniformidade sem outliers) + validate_liquid.py + push + CI real (build + test_links.py) antes de avançar pro próximo:

• Lote A (commit 437f5e16): mod_01 a mod_10.
• Lote B (commit 219016b9): mod_12 a mod_14 + os 7 extra_*.
• Lote C (commit 54ab192c): proj_aplicacoes_full_stack + specs de backend/frontend/mobile (10 módulos).
• Lote D (commit 2352d775, final): spec_seguranca_e_criptografia + os 8 spec_sistemas_com_*.

Resultado: 40/40 módulos com layout: single + sidebar, confirmado por varredura de front matter (zero arquivos dentro do escopo ainda em layout: default — só sobrou nos index.md de subdiretório, slides/, e pastas fora de escopo como projetos/, _legado/, _artefatos/, todos deliberados). CI verde em todos os 4 lotes, ainda 100% em branch (theme/minimal-mistakes), zero exposição em produção.

• A cada lote: build completo + _scripts/test_links.py + amostragem visual (Seção 5.1) antes de fazer merge do lote pra main.
• Site fica no ar com o Cayman até o lote cobrir 100% dos módulos — não dá pra ter os dois temas simultâneos num mesmo _config.yml, então o rollout é feito inteiro numa branch, com merges intermediários revisados, e o deploy real só acontece quando a branch inteira estiver pronta (ou, alternativa mais seguem, ver Nota abaixo).

⚠️ Nota de arquitetura: como o tema é definido uma vez em _config.yml para o site inteiro, não é possível migrar módulo por módulo em produção — todo módulo do site passa a usar o novo tema no mesmo deploy. O “rollout gradual” da Fase 3 é sobre preparar e validar os lotes numa branch de trabalho, não sobre expor parcialmente aos alunos. O corte é único (Fase 4), mas o trabalho de preparação é incremental e cada lote é auditado antes do próximo.

Fase 4 — Corte completo — ✅ CONCLUÍDA 2026-09-01

• Merge da PR #2 (theme/minimal-mistakes → main), commit de merge a3769112/e5959f88.
• Deploy real observado via gh run watch (run 33532310862): build 3m55s + deploy 31s, ambos verdes.
• Checklist pós-deploy feito ao vivo em produção (ricardotecpro.github.io/portal_jekyll): home carrega sem erro, capítulo do mod_11 com sidebar/TOC/Mermaid/H1 único idênticos ao testado na Fase 2, busca global (Ctrl+K) funcionando com o título <script setup> renderizando corretamente (confirma o fix do achado da Fase 2 em produção). Console sem erros em nenhuma página testada.
• Sem toggle de dark mode (decisão R4 — skin dark fixo). Mobile real não testado neste checklist (só o emulado, já coberto a fundo na Fase 2 com o mesmo artefato/código); pendente de confirmação em dispositivo físico.

Site 100% no Minimal Mistakes em produção. Cayman preservado na branch main anterior ao merge (cc326ecf) para referência de rollback (Seção 7).

Fase 5 — Estabilização (em andamento)

• Observar gh run list diariamente por 1 semana.
• Coletar qualquer relato de aluno/professor sobre navegação quebrada.
• Congelar a branch antiga do Cayman (não deletar) por 30 dias como referência de rollback tardio — commit de referência: cc326ecf (último antes do merge da migração).

🧪 5. Plano de testes

5.1 Bateria por módulo (repetir a cada lote da Fase 3, obrigatória na Fase 2)

5.2 Bateria de telas (rodar pelo menos 1x por lote, não em toda página)

Medir sempre via window.innerWidth real (não confiar só no valor pedido ao redimensionar a janela — a ferramenta de automação usada nesta investigação apresentou inconsistência entre o valor solicitado e o efetivo).

5.3 Critérios de aceite da Fase 2 (gate)

A Fase 3 só começa se, no módulo piloto:

• 100% dos itens da tabela 5.1 passam — testado ao vivo em 2026-09-01 (PR #2, branch theme/minimal-mistakes): sidebar auto-colapsada (só mod_11 expandido de 40), H1 único, Mermaid (23 diagramas SVG), MathJax (23 fórmulas), alertas GitHub (2 renderizados, inclusive em página não migrada — head/custom.html chega no site inteiro via o default.html do próprio tema, não só em layout: single), quiz interativo (clique real testado, feedback verde/vermelho correto), busca global (Ctrl+K, resultado real testado), badge de linguagem + botão copiar presentes e com markup correto (clique via automação não confirmou o clipboard, mas é o mesmo código já provado em produção no Cayman)
• 100% dos itens da tabela 5.2 passam nas 3 telas — com 1 ressalva (ver nota abaixo)
• _scripts/test_links.py retorna zero links quebrados — confirmado no CI (run 33525061322)
• Build completo sem erro em tempo aceitável — Risco R1 fechado, ver §6

⚠️ Ressalva achada na bateria de telas: em ~984px (faixa “tablet” definida em §5.2), a sidebar do Minimal Mistakes continua escondida atrás do botão “Abrir menu” — o breakpoint nativo do tema pra virar sidebar persistente é mais alto que a faixa 800-1100px assumida no plano (o TOC, que usa um breakpoint customizado em 768px definido em head/custom.html, já volta pro lado corretamente nessa mesma largura). Não é um bug — é o comportamento padrão do tema — mas é uma divergência da expectativa original. Decisão adiada pra Fase 3: aceitar o breakpoint nativo do MM ou customizá-lo via CSS pra abrir mais cedo.

🐛 Bug real achado e corrigido nesta rodada: 5 capítulos no site (Vue <script setup>/<Transition>, C <string.h>, C#/Java List<T>/<T>) têm títulos com sintaxe literal de tag HTML. gerar_navigation_yml.py gravava isso cru no navigation.yml; o template de sidebar do tema injeta sem escapar, e o navegador interpretava <script setup> como uma tag <script> de verdade, engolindo o resto da página como “código” (tela em branco + SyntaxError no console). Corrigido escapando &/</> no gerador e no JS da busca global (mesmo risco, via search.json).

⚠️ 6. Riscos conhecidos e mitigação

⏮️ 7. Plano de rollback

7.1 Rollback durante as Fases 0-3 (nada em produção ainda)

Trivial — a branch theme/minimal-mistakes simplesmente não é mergeada. Zero impacto em produção. Pode ser abandonada ou retomada a qualquer momento.

7.2 Rollback após a Fase 4 (corte já em produção)

# Reverte o commit de merge do corte (assumindo commit único de merge)
git revert -m 1 <hash-do-commit-de-merge>
git push origin main

• Como o Cayman antigo fica congelado numa branch separada por 30 dias (Fase 5), o revert restaura exatamente o _config.yml, Gemfile, _layouts/, _includes/head-custom.html e assets/css/style.scss de antes — nenhuma perda.
• O conteúdo dos capítulos não precisa de rollback — a migração não altera texto didático, só front matter (layout/sidebar) e a camada de tema. Um git revert do front matter também é seguro porque as mudanças são mecânicas e idempotentes.
• Após o revert: rodar gh run watch no deploy de rollback pra confirmar que o site voltou ao estado anterior antes de considerar o incidente encerrado.

7.3 Rollback parcial (1 módulo com problema, resto ok)

Se só um módulo específico apresentar problema depois do corte completo:

• Reverter o front matter só daquele módulo (git checkout main~N -- mod_XX_.../) restaurando layout: default ali — o resto do site continua no Minimal Mistakes.
• Esse módulo fica temporariamente sem sidebar/TOC (cai no default.html genérico do tema, ainda funcional, só sem o chrome extra) até o problema ser corrigido e reaplicado.

📎 8. Referências

• Auditoria de UI/UX original (Cayman): conversa de sessão 2026-08-31/09-01, achados de acessibilidade, tipografia e busca.
• Comparação de temas (Just the Docs, Minimal Mistakes, Chirpy): mesma sessão, 6 configurações testadas com conteúdo real do Módulo 11.
• Laboratório de testes: scratchpad/theme_lab/ (local, fora do repositório — não versionado; os arquivos definitivos de _includes/head/custom.html e _data/ui-text.yml usados no laboratório devem ser copiados para o repo na Fase 0).