convert-md-to-template-docx

name	convert-md-to-template_docx
description	Converte relatórios Markdown para DOCX com template oficial usando fluxo de 2 etapas (docxcompose) para 100% de preservação de estilos, imagens, fontes e diagramas

Skill: /convert-md-to-template_docx

Converte relatórios técnicos Markdown (.md) para DOCX (.docx) usando o template oficial do INSPIRE Meta 7, com renderização de diagramas Mermaid para PNG e syntax highlighting de código.

Utiliza fluxo de 2 etapas com docxcompose para garantir 100% de preservação de todos os elementos: estilos, fontes, imagens do header/footer (logos INSPIRE/CPQD), tabelas, diagramas e configurações.

Instruções de Execução

Este skill utiliza o fluxo de 2 etapas com docxcompose para garantir 100% de preservação de todos os elementos (estilos, fontes, imagens do header/footer, tabelas, diagramas).

Quando este skill for invocado:

1. Se receber --all: Para cada arquivo .md em docs/relatorios/:

   • Passo 1: Execute python scripts/convert_md_to_docx.py docs/relatorios/{arquivo.md} (conversão limpa, sem template)
   • Passo 2: Execute python scripts/merge_docx_with_docxcompose.py "docs\relatorios\templates\Template-Relatório-Técnico-DestaquesGovbr-Tema7.docx" "docs/relatorios/output/{arquivo}.docx" "docs/relatorios/output/{arquivo}-FINAL.docx"

2. Se receber nome de arquivo: Execute o fluxo de 2 etapas:

   • Passo 1: Execute python scripts/convert_md_to_docx.py docs/relatorios/{arquivo.md} (conversão limpa, sem template)
   • Passo 2: Execute python scripts/merge_docx_with_docxcompose.py "docs\relatorios\templates\Template-Relatório-Técnico-DestaquesGovbr-Tema7.docx" "docs/relatorios/output/{arquivo}.docx" "docs/relatorios/output/{arquivo}-FINAL.docx"
   • Informe ao usuário que o arquivo final está em {arquivo}-FINAL.docx

3. Se NÃO receber argumentos:

   • Use Glob para listar arquivos .md em docs/relatorios/*.md
   • Mostre a lista formatada ao usuário com índices numerados
   • Use AskUserQuestion para perguntar qual arquivo converter (incluir opção "Todos")
   • Execute o fluxo de 2 etapas para o(s) arquivo(s) escolhido(s)

Comportamento

• Com arquivo: /convert-md-to-template_docx {arquivo.md} → converte o arquivo especificado (100% preservação via docxcompose)
• Com --all: /convert-md-to-template_docx --all → converte todos os .md em docs/relatorios/ (100% preservação)
• Sem argumentos: /convert-md-to-template_docx → lista arquivos disponíveis e pergunta ao usuário qual converter

Método: Sempre usa fluxo de 2 etapas (MD → DOCX limpo → Merge com template via docxcompose) para garantir preservação total.

Uso

# Converter arquivo específico (100% preservação)
/convert-md-to-template_docx Relatório-Técnico-DestaquesGovbr-Requisitos-Ingestão-26-03-24.md

# Converter todos os relatórios (100% preservação)
/convert-md-to-template_docx --all

# Sem argumentos: listar e escolher
/convert-md-to-template_docx

Nota: Todos os modos usam o fluxo de 2 etapas com docxcompose para garantir 100% de preservação.

Template Utilizado

O script usa o template oficial:

• Caminho: docs\relatorios\templates\Template-Relatório-Técnico-DestaquesGovbr-Tema7.docx
• Conteúdo preservado:
  • Capa com logo INSPIRE Meta 7
  • Informações do convênio (MGI/Finep)
  • Histórico de versões
  • Nível de sigilo
  • Cabeçalho e rodapé formatados
  • Margens configuradas (1.27cm)

Dependências

Sistema (obrigatório)

• pandoc - Conversor universal de documentos

  # macOS
  brew install pandoc
  
  # Linux
  apt install pandoc
  
  # Windows
  choco install pandoc
  

• mermaid-cli - Renderizador de diagramas Mermaid

  npm install -g @mermaid-js/mermaid-cli
  

Python (obrigatório)

• pypandoc - Wrapper Python do Pandoc

  pip install pypandoc
  # ou
  poetry add pypandoc
  

• python-docx - Manipulação de arquivos DOCX

  pip install python-docx
  # ou
  poetry add python-docx
  

Outputs

Os arquivos gerados ficam em:

• docs/relatorios/output/*.docx - Arquivos DOCX prontos para MS Word com template aplicado
• docs/relatorios/output/imgs/*.png - Diagramas Mermaid renderizados (cache compartilhado)

Características do DOCX Gerado

Estrutura

• Template preservado: Capa, cabeçalho, rodapé e formatações originais
• Conteúdo MD: Inserido após o parágrafo "Sumário"

Fontes

• Texto normal: Arial 11pt
• Código fonte: Courier New 11pt

Código

• Syntax highlighting: Pygments (cores automáticas por linguagem)
• Fundo cinza claro em blocos de código
• Código inline: Courier New

Diagramas

• Mermaid → PNG: Renderizados automaticamente
• Largura ajustada: 6in (caber na página A4)
• Cache: PNG reutilizado se diagrama não mudar
• Erro: Placeholder textual se falhar renderização

Tabelas

• Apenas bordas horizontais (sem bordas laterais)
• Cabeçalho: Borda preta grossa + negrito
• Linhas: Bordas cinza finas
• Largura: 100% da página

Outros

• Hyperlinks: Preservados (externos e internos)
• Links internos: Funcionais (âncoras entre seções)
• TOC (Sumário): Título convertido para "Sumário"
• Emojis: Removidos automaticamente (exceto ✅ ❌ em tabelas)

Diferença vs /convert-md-to-docx

Característica	convert-md-to-docx	convert-md-to-template_docx
Template	Não usa	✅ Template oficial INSPIRE
Cabeçalho/Rodapé	Genérico	✅ CPQD + Relatório Técnico (100% preservado)
Capa	Não tem	✅ Capa oficial com logo
Diagramas Mermaid	✅ Renderiza PNG	✅ Renderiza PNG
Syntax highlighting	✅ Sim (pygments)	✅ Sim (pygments)
Tabelas	✅ Bordas horizontais	✅ Bordas horizontais
TOC (Sumário)	Automático (3 níveis)	Do template
Método	Conversão direta	Conversão + Merge (docxcompose)
Preservação	~95%	100% (todas imagens, estilos, fontes)

Conclusão: /convert-md-to-template_docx usa fluxo de 2 etapas com docxcompose para garantir 100% de preservação de todos os elementos do template oficial INSPIRE.

Como Funciona (Fluxo de 2 Etapas com 100% Preservação)

Passo 1: Conversão MD → DOCX Limpo (sem template)

Usa convert_md_to_docx.py:

1. Processa diagramas Mermaid:

   • Extrai blocos ```mermaid do MD
   • Renderiza cada diagrama para PNG usando mermaid-cli (mmdc)
   • Substitui blocos por ![Diagrama](./imgs/diagram.png) no MD
   • Cache: reutiliza PNG se diagrama não mudar (hash MD5)

2. Converte MD → DOCX via Pandoc:

   • Usa pypandoc com --highlight-style=pygments
   • Syntax highlighting automático por linguagem
   • Gera DOCX limpo com todo conteúdo formatado (sem template)

3. Aplica customizações:

   • Remove bookmarks automáticos do Pandoc
   • Preserva hyperlinks (externos e internos)
   • Configura margens, estilos, tabelas, código

Passo 2: Merge com Template usando docxcompose

Usa merge_docx_with_docxcompose.py:

1. Carrega documentos:

   • Template INSPIRE (capa, cabeçalho, rodapé, logos)
   • DOCX limpo gerado no Passo 1

2. Merge com docxcompose:

   • Biblioteca especializada preserva 100% de todos os elementos
   • Template fica no início, conteúdo do MD logo após
   • Todas as imagens preservadas (5 do template + 10 diagramas)
   • Todos os estilos, fontes, relationships preservados

3. Salva resultado final:

   • DOCX com template + conteúdo + todas as imagens/estilos
   • Arquivo final: {nome}-FINAL.docx

Troubleshooting

Erro: "mmdc not found"

npm install -g @mermaid-js/mermaid-cli

# Verificar instalação
mmdc --version

Erro: "pandoc not found"

# macOS
brew install pandoc

# Linux
apt install pandoc

# Windows
choco install pandoc

# Verificar instalação
pandoc --version

Erro: "pypandoc não está instalado"

pip install pypandoc
# ou com Poetry
poetry add pypandoc

Erro: "python-docx não está instalado"

pip install python-docx
# ou com Poetry
poetry add python-docx

Erro de renderização Mermaid

• Verifique sintaxe do diagrama no Mermaid Live Editor
• Diagramas muito complexos podem ter timeout (30s)
• Se persistir, o script cria um placeholder e continua
• Mensagem: [AVISO] Erro no diagrama X: ...

Limpar cache de diagramas

# Se houver problemas com imagens antigas (cache compartilhado)
rm -rf docs/relatorios/output/imgs/

Limitações Conhecidas

1. Diagramas Mermaid complexos: Gantt ou flowcharts muito grandes podem ter timeout (30s)
2. Tabelas largas: Podem ficar apertadas em páginas A4 (Pandoc faz wrap automático)
3. TOC: Título convertido para "Sumário", mas links internos podem não funcionar perfeitamente
4. Estilos do template: Alguns estilos do Pandoc podem não combinar 100% com o template
5. Posição do conteúdo: Sempre adicionado após o template (não há opção de inserir em posição específica)

Quando Usar Esta Skill vs Outras

Use /convert-md-to-template_docx quando:

• ✅ Precisa do template oficial INSPIRE com capa/cabeçalho/rodapé
• ✅ Quer relatórios com identidade visual padronizada CPQD
• ✅ Vai entregar para MGI/Finep com logo e formatação oficial
• ✅ Precisa de 100% de preservação de todos os elementos (imagens, estilos, fontes)
• ✅ Precisa de diagramas Mermaid renderizados + syntax highlighting + template

Use /convert-md-to-docx quando:

• ✅ Não precisa do template oficial
• ✅ Quer customizar completamente os estilos
• ✅ Precisa de TOC automático (3 níveis)
• ✅ Quer controle total sobre margens e formatação

Use /convert-md-to-odt quando:

• ✅ Usa LibreOffice ao invés de MS Word
• ✅ Precisa de formato OpenDocument
• ✅ Trabalha em ambiente Linux sem MS Office

---

🎯 O que é Preservado (100%)

Este skill usa a biblioteca especializada docxcompose no Passo 2 que preserva ABSOLUTAMENTE TUDO:

• ✅ Todos os estilos e fontes de ambos os documentos
• ✅ Todas as imagens (5 logos do template + 10 diagramas Mermaid = 15 imagens)
• ✅ Relationships (links internos entre XML e arquivos de imagem)
• ✅ Formatação de tabelas com bordas, cores e estilos
• ✅ Configurações de página (margens, tamanhos, orientação)
• ✅ Numeração de listas e hierarquia
• ✅ Header e footer com todos os elementos e imagens
• ✅ Arquivos de mídia (renomeia automaticamente para evitar conflitos)
• ✅ Diagramas e gráficos embarcados
• ✅ Campos dinâmicos (data, numeração de páginas, etc.)

Exemplo de Resultado

Template (5 imagens) + Conteúdo (10 diagramas) = FINAL (15 imagens)
  
  Arquivos no DOCX final:
  - image1.png a image5.png   → logos INSPIRE/CPQD do template
  - image6.png a image15.png  → diagramas Mermaid (renomeados automaticamente)

Links

Scripts

• convert_to_docx_with_template.py - Conversão MD → DOCX com template
• merge_docx_with_docxcompose.py - Merge de DOCX com preservação total (100%)
• convert_md_to_docx.py - Conversão MD → DOCX sem template

Templates

• Template Relatório Técnico INSPIRE

Documentação

• python-docx Documentation
• docxcompose Documentation
• Pandoc Documentation
• Mermaid Documentation