Um README é prático para rever um projeto, mas a mesma informação pode precisar de um documento estável para uma reunião, uma entrega ou um arquivo. Converter Markdown em PDF permite manter uma fonte em texto simples e entregar uma cópia com páginas, margens e texto selecionável. O trabalho não termina ao obter um ficheiro com extensão .pdf: é necessário confirmar se a estrutura, as ligações, as tabelas e o código continuam a comunicar corretamente depois da paginação.
Este guia cria um README reproduzível e converte-o com a ferramenta Markdown para PDF. A UtilX processa a entrada no navegador e só exporta quando solicitado. O exemplo não contém informação confidencial e distingue aquilo que a pré-visualização mostra daquilo que deve ser verificado no PDF.
Definir o documento antes de o formatar
Markdown descreve estrutura através de convenções de texto. CommonMark separa blocos, como títulos, parágrafos, citações, listas, separadores e blocos de código, de conteúdo em linha, como ligações, ênfase e código. GitHub Flavored Markdown acrescenta tabelas, itens de tarefa e texto rasurado. O conversor mapeia estas estruturas para um modelo de páginas; não consegue manter exatamente a largura fluida de um navegador.
Comece por definir o objetivo e o leitor. Neste exemplo, uma equipa precisa de uma lista de publicação disponível offline. O PDF deve ser legível em papel A4, conservar ligações HTTPS clicáveis, mostrar código como código e distinguir tarefas concluídas. São requisitos verificáveis. “Parece igual em todo o lado” não é: a pré-visualização e o PDF usam motores de composição diferentes, pelo que as quebras de linha e de página podem variar.
Um exemplo completo de README
Crie release-readme.md com o conteúdo sintético seguinte. Abrange a sintaxe suportada sem depender de ficheiros remotos:
# Lançamento Atlas 1.4
**Responsável:** equipa de documentação
*Janela:* 18 de setembro de 2026
~~Objetivo anterior: 1.3~~
> Publicar apenas depois de verificar a reversão.
## Lista
- [x] Bloquear traduções
- [ ] Publicar pacote
- [x] Verificar checksum
- [ ] Copiar a nota de versão
## Comandos
Execute `npm test` e depois:
~~~sh
npm run build
npm run smoke
~~~
## Ambientes
| Nome | URL | Responsável |
| --- | --- | --- |
| Testes | [estado](https://example.com/status) | Plataforma |
| Produção | pendente | Operações |
---
Consulte o [procedimento](https://example.com/runbook).
O PDF esperado contém um título principal, três metadados —responsável, janela e objetivo anterior rasurado—, uma citação, tarefas aninhadas, código em linha e em bloco, uma tabela de três colunas, um separador e duas ligações. Não se fixa o número de páginas: depende do papel, das margens, do tamanho de letra e da quebra de linhas.
Converter e verificar passo a passo
Abra a ferramenta localizada e cole o exemplo ou importe o .md. Mantenha a fonte abaixo de 200 KiB em UTF-8; entradas maiores são recusadas antes da análise. Na pré-visualização, reveja a hierarquia e não os limites de página. Confirme que o título se distingue do corpo, que tarefas abertas e concluídas são diferentes, que itens aninhados permanecem sob o item pai e que a tabela conserva três colunas.
Escolha A4, margens de 20 mm, corpo de 12 pt e numeração. Dê à transferência um nome descritivo, como atlas-1-4-lancamento.pdf, e exporte explicitamente. Alterar a fonte não deve iniciar uma transferência. Abra o PDF guardado num leitor separado. Selecione e copie uma frase para confirmar que o corpo é texto, não uma captura. Procure reversão, ative as duas ligações HTTPS e amplie o bloco de comandos e a tabela.
Repita com Letter se o destinatário imprimir nesse formato. Compare significado e legibilidade, não coordenadas. Uma tabela estreita pode quebrar de forma diferente e um título pode passar à página seguinte. Se uma linha ficar difícil de ler, encurte as células ou converta-a numa lista antes de reduzir o documento inteiro.
O que cada opção realmente altera
A4 e Letter têm dimensões diferentes, portanto o mesmo parágrafo pode ocupar outro número de linhas. As margens de 12, 20 e 28 mm alteram a área de escrita. Os corpos de 10, 12 e 14 pt mudam a densidade e a legibilidade. Estas escolhas interagem: aumentar simultaneamente margens e letra provoca quebras mais cedo e normalmente mais páginas.
Os números de página são um elemento opcional da saída. Facilitam a discussão de uma cópia fixa, mas não fazem parte de Markdown. A geração distribui o conteúdo num tamanho de página fechado e pode colocar um número dinâmico no rodapé. O documento exportado mantém texto selecionável e ligações suportadas. A pré-visualização aproxima honestamente estilo e ordem, não garante paginação idêntica.
A primeira versão suporta títulos, parágrafos, negrito, itálico, rasurado, ligações HTTP(S) e mailto, listas ordenadas ou não ordenadas aninhadas, listas de tarefas, citações, separadores, código em linha e delimitado e tabelas GFM. É importante enumerar este conjunto porque os dialetos Markdown diferem. Uma extensão funcionar num repositório não significa que todos os conversores a compreendam.
Resolver falhas comuns
Se uma lista perder o nível, reveja a indentação e deixe uma linha vazia perto dos blocos adjacentes. Se uma tabela aparecer como barras verticais literais, assegure que tem cabeçalho, linha delimitadora e as mesmas colunas lógicas em cada linha. Se o código absorver formatação posterior, feche a cerca com o mesmo marcador e pelo menos o comprimento da abertura. Estas verificações seguem regras de blocos, não o espaçamento visual de um editor específico.
Imagens remotas e referências a ficheiros locais não são carregadas. O conversor mostra o texto alternativo e um aviso para tornar a omissão visível. Escreva um alt útil e anexe imagens aprovadas separadamente se o processo final as exigir. HTML bruto é mostrado literalmente com um aviso; não é executado. Não utilize uma etiqueta HTML para contornar uma limitação de composição.
Se a exportação parar, verifique primeiro o tamanho em UTF-8. Dividir um documento grande em capítulos coerentes é mais seguro do que apagar avisos ou código sem critério. Se uma ligação falhar, confirme que começa por https://, http:// ou mailto: e teste-a tanto na pré-visualização como no PDF exportado.
Decisões para uma entrega duradoura
Mantenha Markdown como fonte editável e trate o PDF como uma saída datada. Registe papel, margem, corpo, numeração e data da ferramenta junto do processo. Outro revisor poderá reproduzir a exportação em vez de editar um PDF opaco. Para documentos controlados, guarde em conjunto a revisão da fonte e o ficheiro exportado.
Use títulos em ordem e texto de ligação descritivo. Não dependa apenas de cor para indicar o estado de uma tarefa. Mantenha linhas de código razoavelmente curtas e tabelas compactas; ambas têm uma largura natural que o papel pode não acomodar. Uma lista é muitas vezes mais robusta do que uma tabela com prosa longa. Antes de partilhar, leia o PDF no zoom normal e com seleção ou pesquisa, não apenas em miniaturas.
O processamento no navegador evita que esta conversão precise de enviar o Markdown introduzido para o servidor da aplicação, mas o ficheiro transferido continua no fluxo normal de armazenamento do navegador e do sistema. Aplique as mesmas regras de classificação e partilha usadas para qualquer documento exportado.
Limites do conversor
A primeira versão não representa matemática, diagramas Mermaid, HTML personalizado ou conteúdo executável. Não obtém imagens remotas nem ficheiros referenciados. Também não promete paginação ou píxeis idênticos entre vista e PDF, conformidade de arquivo, acessibilidade de PDF etiquetado, assinaturas digitais, cifragem ou preservação de plugins específicos do repositório. Um PDF abrir não demonstra que seja acessível, aprovado ou completo.
Tabelas complexas podem continuar difíceis de ler mesmo sendo válidas. Para evitar recortes, a indentação no PDF deixa de aumentar depois de seis níveis de lista aninhada, embora o conteúdo restante seja preservado. Se a largura disponível deixasse qualquer coluna abaixo de 25 pt, a tabela é recusada com um aviso: divida colunas ou reduza as margens em vez de forçar uma exportação ilegível.
Cadeias sem pontos de quebra e linhas extensas de código podem ajustar-se de forma estranha. A exportação acrescenta oportunidades de quebra e alguns leitores PDF podem inserir espaços quando o texto copiado atravessa esses pontos. Se um comando tiver de ser exato, copie a linha longa do PDF e compare-a carácter a carácter com a fonte Markdown antes de a executar. Os leitores também tratam ligações e fontes de forma diferente. Teste o ficheiro exportado no ambiente em que será usado e recorra a publicação especializada quando forem necessárias tipografia exata, acessibilidade avançada ou conformidade.
Lista final de verificação
Confirme que a fonte usa UTF-8 e não excede 200 KiB. Verifique títulos, ênfase, rasurado, ligações, listas aninhadas e de tarefas, citações, separadores, código e tabelas contra o significado pretendido. Reveja cada aviso de imagem e cada aviso de HTML literal. Exporte com A4 ou Letter, margens de 12, 20 ou 28 mm, corpo de 10, 12 ou 14 pt e a opção de numeração acordada.
Abra o PDF transferido separadamente. Selecione e copie texto, procure uma frase conhecida, siga as ligações importantes e inspecione colunas, código e transições entre páginas. Compare conteúdo e hierarquia com o README sem exigir paginação idêntica à pré-visualização. Por fim, mantenha a fonte e as definições junto do PDF verificado para que outra pessoa possa reproduzir o resultado.
Fontes: especificação CommonMark, especificação GitHub Flavored Markdown e documentação da definição de documentos do pdfmake.