Extra Documentação Técnica com Markdown • Trilha Progressiva em 4 Níveis

🎯 Nível 1: Fundamentos

Problema 17.1 — Linha de Comando Canônica para Geração de PDF com Sumário

Contexto: Executar o Pandoc para converter um arquivo relatorio.md em relatorio.pdf incluindo sumário automático (--toc) e numeração de seções (-N).

Requisitos de Execução:

  1. Especificar o arquivo de entrada relatorio.md.
  2. Definir a flag de saída -o relatorio.pdf.
  3. Adicionar as flags --toc (Table of Contents) e -N (Number Sections).

Resultado Esperado

pandoc relatorio.md -o relatorio.pdf --toc -N --pdf-engine=xelatex

📤 Instruções de Entrega (Microsoft Teams)

  1. Salve o arquivo como: Atividade_17_1_SeuNome.sh
  2. Envie na tarefa: Atividade Cap 17 - Pandoc e Conversão Universal
🔑 Gabarito de Código & Solução Comentada 
pandoc relatorio.md -o relatorio.pdf --toc -N --pdf-engine=xelatex

Comentário: A flag --toc analisa todos os cabeçalhos do documento e cria o índice clicável com numeração de páginas correspondente.

🎯 Nível 2: Prática

Problema 17.2 — Exportação de Markdown para DOCX com Modelo Corporativo

Escreva o comando para compilar um arquivo proposta.md em formato Microsoft Word (proposta.docx), aplicando estilos e cabeçalhos visuais a partir de um arquivo de referência --reference-doc=template.docx.

🔑 Gabarito de Código & Solução Comentada 
pandoc proposta.md -o proposta.docx --reference-doc=template.docx --toc

🎯 Nível 3: Integração

Problema 17.3 — Filtro Lua para Pandoc: Adicionar Ícone em Links Externos

Escreva um filtro Lua simples (link_externo.lua) para o Pandoc que examine todos os links: se o link começar com http:// ou https://, adicione o atributo target="_blank" e um emoji de link externo ` ↗`.

🔑 Gabarito de Código & Solução Comentada 
-- link_externo.lua
function Link(el)
  if el.target:match("^https?://") then
    table.insert(el.content, pandoc.Str(" ↗"))
    el.attributes["target"] = "_blank"
    el.attributes["rel"] = "noopener noreferrer"
  end
  return el
end

-- Uso:
-- pandoc entrada.md -o saida.html --lua-filter=link_externo.lua

🎯 Nível 4: Desafio

Problema 17.4 — Script de Automação de Publicação Multi-Formato em Python

Crie um script em Python que automatize a geração simultânea de versões em PDF, DOCX e EPUB a partir de uma pasta de capítulos Markdown, concatenando-os ordenadamente com metadados de capa.

🔑 Gabarito de Código & Solução Comentada 
# build_multiformat_book.py
import subprocess
import os

def compilar_livro():
    capitulos = ["cap01.md", "cap02.md", "cap03.md"]
    metadados = "--metadata title='Manual de Engenharia' --metadata author='Equipe de Arquitetura'"
    
    # 1. Gerar PDF
    cmd_pdf = f"pandoc {' '.join(capitulos)} {metadados} -o build/manual.pdf --toc -N"
    print("Compilando PDF...")
    # subprocess.run(cmd_pdf, shell=True, check=True)
    
    # 2. Gerar DOCX
    cmd_docx = f"pandoc {' '.join(capitulos)} {metadados} -o build/manual.docx --toc"
    print("Compilando Word...")
    
    # 3. Gerar EPUB
    cmd_epub = f"pandoc {' '.join(capitulos)} {metadados} -o build/manual.epub --toc"
    print("Compilando EPUB...")
    
    print("✅ Todos os 3 formatos compilados com sucesso!")

if __name__ == "__main__":
    compilar_livro()