De Markdown para PDF e de volta: o que a conversão de formato preserva
Markdown↔PDF preserva títulos, listas e tabelas simples melhor do que pixels. Fontes exatas, paginação e layout não sobrevivem como ida e volta sem perdas.
Markdown e PDF são otimizados para contratos diferentes. Markdown é estrutura amigável a controle de versão. PDF é uma descrição fixa de página. Converter num sentido e depois no outro é útil, mas não é um ciclo de arquivamento sem perdas.
De Markdown para PDF: a estrutura vira páginas
O Markdown para PDF (POST /api/v1/convert/markdown/pdf) aceita um arquivo .md ou um ZIP que contenha Markdown. Envios que não sejam Markdown nem ZIP são rejeitados. UTF-8 é obrigatório para a entrada em .md puro. O fluxo renderiza o Markdown em HTML com tabelas, riscado e listas de tarefas habilitados, envolve esse HTML em CSS voltado à impressão (incluindo pilhas de fontes para vários alfabetos e RTL quando árabe é detectado) e então imprime em PDF com o WeasyPrint.
O que costuma sobreviver na ida:
- Títulos, parágrafos, listas e tabelas Markdown simples
- Texto em vários alfabetos que o caminho HTML consiga compor (CJK, latino e outros cobertos pelo CSS de impressão)
- Um PDF imprimível e compartilhável para fluxos de documentação como código
O que não sobrevive:
- As fontes do tema do seu editor como correspondência garantida em qualquer visualizador
- As quebras de linha exatas da tela que existiam no arquivo
.md - Recursos interativos do Markdown sem equivalente em PDF (caixas de seleção ao vivo, seções recolhíveis, links de wiki)
Uma entrada em ZIP serve para empacotar o Markdown com arquivos que o caminho HTML consegue resolver ao lado do documento. Trate isso como conveniência de empacotamento, não como garantia de que toda imagem relativa ou referência CSS vai parecer igual em qualquer visualizador.
De PDF para Markdown: entra a camada de texto, sai Markdown
O PDF para Markdown (POST /api/v1/convert/pdf/markdown) extrai o conteúdo textual para Markdown via pdf-inspector. A resposta é text/markdown, baixada como arquivo .md. PDFs nativos digitais, com camada de texto limpa, convertem melhor. Páginas digitalizadas sem camada de texto produzem Markdown vazio ou inútil enquanto você não aplicar OCR antes, e o OCR deste site também devolve Markdown, não uma camada pesquisável em PDF.
Espere encontrar:
- Títulos e parágrafos quando as heurísticas de tamanho de fonte acertam (talvez você ainda precise renumerar os níveis
#à mão) - Tabelas como tabelas Markdown quando o reconhecimento funciona; diagramações em várias colunas podem linearizar numa ordem de leitura diferente
- Cabeçalhos e rodapés repetidos a cada página (corte na edição posterior)
- Imagens e equações em forma de figura que não se tornam automaticamente arquivos locais nem LaTeX
Se você precisa de texto corrido sem heurísticas de título, o PDF para texto é a extração mais plana. Exportações em formato de tabela que retornam HTTP 204 significam que nenhum bloco em colunas foi detectado; veja Exportação de tabela vazia (204).
O que uma ida e volta realmente prova
| Sobrevive razoavelmente | Normalmente não sobrevive |
|---|---|
| Palavras, hierarquia de títulos, estrutura de listas | Geometria de página idêntica ao pixel |
| Tabelas simples como texto | Fontes e kerning exatos |
| Um rascunho útil para o Git ou para agentes | Paginação idêntica à da impressão |
Fazer a ida e volta duas vezes gera divergência. Markdown→PDF reflui pelo WeasyPrint; PDF→Markdown reconstrói a estrutura a partir de heurísticas de extração. Nenhum dos dois passos guarda um intermediário sem perdas do modelo de layout do outro formato.
Escolha uma direção canônica
Se o layout impresso é o seu sistema de registro, mantenha o PDF e trate o Markdown como exportação ou alimentação de agente. Se você precisa de diffs, revisão de código e ingestão por agentes, prefira o Markdown e trate o PDF como etapa de publicação. Não guarde os dois como "fontes da verdade" equivalentes esperando que continuem idênticos depois das edições.
Um ciclo prático de documentação como código: edite o Markdown no Git → Markdown para PDF para gerar o artefato compartilhável → evite PDF→Markdown→PDF como hábito diário. Use PDF→Markdown quando você herdou um PDF nativo digital e precisa do texto para um agente; depois trate esse Markdown como um rascunho novo, não como garantia da paginação original.
Arquivos criptografados precisam de um Desbloquear autorizado antes de qualquer conversão. Arquivos danificados que não podem ser interpretados devem passar antes por Get Info / Repair. Para os mesmos endpoints por HTTP, veja Desenvolvedores.