Quebra de página Markdown PDF: comece uma página nova exatamente onde você quer

Por que o Markdown não tem quebra de página

O Markdown foi criado para a web, e uma página web não tem páginas. Nem a sintaxe original nem o CommonMark definem uma quebra de página. O mais próximo é uma linha com três hífens ---, uma quebra temática: ela vira uma linha <hr>, não uma página nova. Muita gente tenta isso primeiro como quebra de página e depois não entende por que nada acontece.

O que o Markdown permite é HTML puro. A maioria dos exportadores converte o Markdown em HTML e depois imprime esse HTML como PDF; então uma quebra de página é, na prática, uma regra CSS num elemento HTML. A exceção é o caminho padrão do Pandoc, que passa pelo LaTeX e espera um comando LaTeX.

Trechos de quebra de página que funcionam

Escolha a linha que combina com o seu exportador e coloque-a sozinha numa linha, com uma linha em branco antes e depois, para o parser de Markdown tratá-la como um bloco HTML:

Last paragraph of the first part.

<div style="page-break-after: always"></div>

## Part two

This heading starts a new page.

• CSS moderno: <div style="break-after: page"></div>, ou break-before: page no elemento que deve abrir a página.
• Direto num título: <h2 style="page-break-before: always">Parte dois</h2>, se você não se importa de escrever esse título em HTML.
• Extensão Markdown PDF do VS Code: o README dela indica <div class="page"/>; a folha de estilos da extensão gera a quebra. É a resposta comum para o VS Code, e o estilo inline acima também funciona lá.
• Pandoc com LaTeX (o caminho padrão para PDF): uma linha com \newpage. A extensão raw_tex só repassa isso sem mudanças para os writers de LaTeX e ConTeXt. O comando newpage do Pandoc não serve para saída HTML; se você usa um motor HTML para o PDF, use a div.

Por que dois nomes? A especificação CSS de fragmentação trocou page-break-before e page-break-after por break-before e break-after, mantendo os nomes antigos como apelidos: page-break-after: always funciona igual a break-after: page. A forma antiga é a escolha mais segura para ferramentas mais velhas; o MDN documenta as duas.

Como nosso exportador trata uma quebra manual

Até 19 de out. de 2026, nosso exportador ignorava quebras de página manuais e escolhia cada corte sozinho. Agora ele lê os valores calculados break-before e break-after de cada elemento do documento renderizado, então uma quebra de página CSS num atributo style é respeitada, na grafia antiga ou na nova. A prévia ao vivo desenha uma linha tracejada com o rótulo "Quebra de página" onde a página nova começa, e depois da exportação um aviso diz quantas quebras manuais foram aplicadas.

Algumas regras mantêm o resultado limpo:

• Uma quebra bem no início ou bem no fim do documento é ignorada, então você nunca fica com a primeira ou a última página em branco.
• Duas quebras seguidas contam como uma. O Chrome imprime uma página em branco entre elas; supomos que quase nunca é isso que você quer.
• Os valores left, right, recto e verso começam uma página nova. Não adicionamos uma página em branco para cair numa página da esquerda ou da direita.
• --- continua sendo uma linha horizontal, como o Markdown define.
• As quebras automáticas continuam valendo dentro de seções longas e continuam evitando cortar uma linha, uma linha de tabela ou uma imagem.

O que testamos, comparado com imprimir pelo Chrome

Escrevemos 9 documentos pequenos, cada um testando um jeito de escrever uma quebra de página. Exportamos todos pelo botão real Baixar PDF e lemos de volta com pdfinfo e pdftotext para ver que texto foi parar em que página. Como referência, também imprimimos o mesmo HTML com a impressora de PDF do Chrome. Nos nossos testes, todos os 9 casos deram as páginas esperadas sem páginas em branco, e 8 de 9 bateram com o Chrome página por página.

Manter o título junto do texto, e outros cortes ruins

As quebras manuais resolvem os pontos que você conhece. O resto fica com o exportador, e o erro clássico é um título sozinho no pé da página enquanto o texto dele começa na seguinte. Os editores de texto chamam a solução de "manter com o próximo". Em CSS, a regra equivalente é break-after: avoid nos títulos, mas o suporte aos valores avoid na impressão muda de um motor para outro; teste antes de confiar.

Nosso exportador faz isso sem marcação nenhuma: um título fica junto da primeira linha que vem depois dele, e linhas de tabela e imagens não são divididas se couberem numa página. Se mesmo assim você não gostar de onde uma página termina, coloque uma quebra de página manual logo antes do título. A imagem abaixo mostra onde um corte pode cair e onde não pode.

Tabelas pedem um cuidado especial. Nosso guia para imprimir tabelas trata de tabelas longas e largas, e uma exportação rápida com MD para PDF é o jeito mais rápido de testar um layout antes do documento de verdade.

Erros comuns com quebras de página

Quando uma quebra de página não faz nada, quase sempre é por um destes quatro motivos:

• Falta a linha em branco depois da div. No CommonMark, um bloco HTML que começa com <div> vai até a próxima linha vazia. O texto logo abaixo é engolido pelo HTML e aparece sem formatação, com ## e ** como caracteres literais.
• A div está dentro de uma lista, citação ou tabela. Coloque-a no nível mais alto do documento, onde qualquer exportador a vê como um bloco próprio.
• O HTML puro está desativado. Alguns renderizadores desativam HTML por padrão e mostram a tag como texto. Ative o HTML nas configurações ou use a sintaxe de quebra da própria ferramenta, se houver.
• Julgar pela prévia. Prévias que limpam o HTML costumam remover estilos inline, então a quebra parece não existir na tela, mas funciona na exportação. Nossa prévia mostra a marca tracejada, mas o teste de verdade é o arquivo exportado.

Outro hábito ajuda: coloque cada quebra manual logo acima do título da seção que deve começar numa página nova, nunca abaixo. Assim o título e o primeiro parágrafo sempre ficam juntos, e se você apagar a quebra depois, o documento continua na ordem certa.

Checagem rápida antes de compartilhar o PDF

1. Passe por todas as páginas procurando páginas em branco; geralmente elas indicam duas quebras seguidas ou uma quebra no fim.
2. Confira se cada seção começa no topo da página, com o título primeiro.
3. Pesquise uma palavra da última página para confirmar que a camada de texto é real.
4. Se o PDF for impresso frente e verso e os capítulos precisarem começar na página da direita, use uma ferramenta que suporte break-before: right; a nossa trata isso como uma página nova comum.