Exportar um README do GitHub e sua documentação para PDF

Por Fazt · Atualizado em 7 de outubro de 2026

Um README é escrito para quem navega por um repositório, mas cedo ou tarde alguém precisa dele como documento: um cliente que vai aprovar uma entrega, um auditor que pede a documentação de uma versão específica ou você mesmo, querendo uma cópia offline. O GitHub exibe Markdown muito bem na tela, mas não tem um botão para transformar um arquivo em PDF. Como um README é só Markdown, você pode pegar o texto-fonte, corrigir o pouco que só faz sentido dentro de um repositório e imprimi-lo com uma tipografia caprichada. Precisa do caminho inverso, do Word para um README? Veja Transformar um documento do Word em README do GitHub.

1. Pegue o Markdown bruto

Para um único arquivo, abra-o no GitHub (clique em README.md na lista de arquivos, não na página inicial do repositório) e clique em Raw no canto superior direito da visualização do arquivo. Selecione todo o texto puro, copie e cole no painel de Markdown do editor. O ícone de copiar ao lado de Raw faz o mesmo com um clique.

Para vários arquivos, como uma pasta docs/, traga o repositório para o seu computador. Use Code → Download ZIP ou clone só a versão mais recente:

git clone --depth 1 https://github.com/acme/widget.git

Depois, use Abrir arquivo .md. Ele carrega um único arquivo e substitui o que estiver no editor; a seção 4 mostra como juntar vários arquivos antes.

2. Reescreva os caminhos relativos

No GitHub, ![Captura](docs/captura.png) é resolvido dentro do repositório. A página do editor não está no seu repositório, então o navegador procura docs/captura.png no próprio site do editor, não encontra nada e mostra uma imagem quebrada. Links relativos como [Como contribuir](CONTRIBUTING.md) quebram pelo mesmo motivo.

A solução é tornar todos os caminhos absolutos:

Imagens: https://raw.githubusercontent.com/USUARIO/REPO/BRANCH/caminho/da/imagem.png
Links para outros arquivos: https://github.com/USUARIO/REPO/blob/BRANCH/caminho/do/arquivo.md, para que o leitor chegue à página já renderizada no GitHub.

Um exemplo: no repositório acme/widget, branch main, o arquivo docs/setup.md contém:

![Arquitetura](images/arquitetura.png)
<img src="../assets/logo.svg" width="120">
Veja a [referência de configuração](configuration.md#variaveis-de-ambiente).

Os caminhos são relativos à pasta do arquivo, aqui docs/, e ../ sobe um nível. Então fica assim:

![Arquitetura](https://raw.githubusercontent.com/acme/widget/main/docs/images/arquitetura.png)
<img src="https://raw.githubusercontent.com/acme/widget/main/assets/logo.svg" width="120">
Veja a [referência de configuração](https://github.com/acme/widget/blob/main/docs/configuration.md#variaveis-de-ambiente).

Um caminho que começa com / é relativo à raiz do repositório. Se o PDF documenta uma versão específica, use a tag dela no lugar do branch (…/acme/widget/v2.4.0/docs/…): assim as imagens batem com aquela versão mesmo depois que o main avançar.

Não é preciso editar linha por linha. Clique no painel de Markdown e pressione Ctrl+F (Cmd+F no Mac): o painel de busca tem um campo de substituição e um botão replace all. Procure ](images/ e substitua por ](https://raw.githubusercontent.com/acme/widget/main/docs/images/; depois faça o mesmo com cada atributo HTML src="…" que ainda não seja uma URL completa.

3. O que se mantém do GitHub

O editor entende a maior parte do Markdown do GitHub (compare com a referência de sintaxe do GitHub), mas alguns extras precisam de um pequeno ajuste:

Recurso do GitHub	No PDF	O que fazer
Tabelas, alinhamento de colunas, tachado, notas de rodapé	Funcionam	Nada
Listas de tarefas (`- [x]`)	Funcionam, como caixas marcadas e vazias	Nada
Blocos de código com linguagem	Com destaque de sintaxe em mais de 20 linguagens comuns, como Bash, Python, JavaScript, TypeScript, Go, Rust, Java, C#, SQL e YAML	Outras, como PowerShell, GraphQL, HCL ou Lua, saem como texto monoespaçado sem cores
Diagramas Mermaid	Funcionam, como gráficos vetoriais	Nada
Fórmulas com $…$ e `$$…$$`	Funcionam	Troque blocos ```math por `$$…$$`
Links automáticos	URLs completas (`https://…`) viram links	Escreva como URL completa os endereços `www.`, as issues `#123` e as menções `@usuario`
Alertas (`> [!NOTE]`)	Uma citação comum com `[!NOTE]` à mostra	Troque o marcador por um rótulo em negrito
`<details>` e `<summary>`	Funcionam, mas são impressos recolhidos	Escreva `<details open>`
HTML (`<p align="center">`, `<img width="…">`, `<br>`)	Funciona; scripts são removidos	Torne absolutos os `src` e `href`
Selos (shields.io)	Carregam como qualquer outra imagem	Considere removê-los para leitores sem perfil técnico
Códigos de emoji (`:rocket:`)	Impressos como foram digitados	Cole o próprio emoji (🚀)
Âncoras de títulos	Geradas automaticamente	Confira links para títulos com acentos, símbolos ou emojis

Um alerta fica assim: > [!WARNING] seguido de > Faça backup do banco de dados antes de atualizar. vira > **Atenção:** Faça backup do banco de dados antes de atualizar. No editor, citações aparecem em itálico com uma linha à esquerda.

Os identificadores dos títulos seguem a regra do GitHub nos casos simples: ## Getting started vira #getting-started, e um título repetido ganha -1, -2, então um sumário escrito à mão continua funcionando. A diferença está nos acentos: ## Instalação rápida vira #instalacao-rapida, enquanto o GitHub mantém #instalação-rápida. Se a sua documentação está em português, confira esses links na pré-visualização.

Além disso, no texto comum o editor transforma aspas retas em tipográficas e -- em meia-risca (–); o código não é alterado, então os comandos continuam prontos para copiar.

4. Junte README, documentação e changelog

Para ter um único manual, junte os arquivos em um só Markdown com um marcador de quebra de página entre eles, para que cada um comece em uma página nova. Antes, reescreva os caminhos relativos de cada arquivo: images/fluxo.png não quer dizer a mesma coisa dentro de docs/ e na raiz. Depois, no macOS, no Linux ou no Git Bash:

awk 'FNR==1 && NR>1 {print "\n<!-- pagebreak -->\n"} 1' README.md docs/*.md CHANGELOG.md > handbook.md

No PowerShell:

(Get-Content README.md, docs\*.md, CHANGELOG.md -Raw -Encoding utf8) -join "`n`n<!-- pagebreak -->`n`n" | Set-Content handbook.md -Encoding utf8

O padrão docs/*.md ordena os arquivos em ordem alfabética; liste-os um a um se precisar de outra ordem. Abra o handbook.md com Abrir arquivo .md e faça mais dois ajustes:

Os links entre os arquivos agora apontam para dentro do mesmo documento: troque [Configuração](docs/configuration.md) por [Configuração](#configuracao).
O primeiro título é usado como nome sugerido do PDF, então comece pelo título # do projeto.

Changelogs crescem muito. Para um cliente, as duas ou três últimas versões costumam bastar; corte o resto ou coloque um link para o arquivo completo no GitHub.

5. Use o tema Technical para documentação cheia de código

Abra o painel Estilo. O Technical junta Roboto no texto com JetBrains Mono nos títulos, em verde-escuro, e combina com documentação para desenvolvedores. Não existe um ajuste separado para a fonte do código: os blocos de código usam JetBrains Mono em todos os temas, a 82% do tamanho do texto, então o controle Tamanho da fonte ajusta os dois. Com os 11 pt padrão, em A4 e margens normais, uma linha de código comporta cerca de 85 caracteres; com 10 pt e margens Estreitas, você chega perto de 100.

Para leitores que não programam, Modern ou Clean parecem menos técnicos, e os blocos de código mantêm a fonte monoespaçada de qualquer jeito.

6. Exporte e entregue o PDF

Clique em Baixar PDF e escolha Salvar como PDF na janela de impressão; o editor espera as imagens carregarem antes de abri-la. Desative Cabeçalhos e rodapés para remover a data e o endereço da página. O porém: o editor não tem uma opção de numeração de páginas, então, se o cliente precisar de números de página, deixe cabeçalhos e rodapés ativados e aceite a data, o título e o endereço que o navegador imprime em volta. Evite Mais → PDF rápido para documentação: ele salva as páginas como imagens, e ninguém consegue pesquisar no texto nem copiar um comando.

Antes de enviar um README para pessoas sem perfil técnico:

Remova a fileira de selos e as seções só para desenvolvedores (compilar a partir do código, como contribuir, configuração de CI), ou mova-as para um anexo depois de uma quebra de página.
Adicione abaixo do título uma linha com a versão e a data, por exemplo Versão 2.4 · 7 de outubro de 2026. Sem cabeçalhos, nada mais na página diz qual versão está sendo lida.
Escreva textos de link que façam sentido no papel, ou mostre o endereço completo, porque não dá para clicar em uma folha impressa.

Solução de problemas

Uma imagem aparece quebrada ou só mostra o texto alternativo. O caminho ainda é relativo ou o repositório é privado: imagens de um repositório privado não são públicas, então não carregam no editor. Hospede a imagem em um lugar público ou incorpore-a: codifique com base64 -w0 diagrama.png (Linux e Git Bash; base64 -i diagrama.png no macOS) e escreva ![Diagrama](data:image/png;base64,iVBOR…). Funciona com PNG, JPEG, GIF e WebP, mas não com SVG.
As imagens aparecem na pré-visualização, mas não no PDF rápido. O PDF rápido redesenha a página em um canvas, e o navegador só permite isso com imagens cujo servidor autoriza o uso entre origens (CORS). raw.githubusercontent.com e img.shields.io autorizam; alguns outros servidores não. Baixar PDF imprime qualquer imagem que a pré-visualização mostre.
Linhas de código longas. Elas continuam na linha de baixo em vez de serem cortadas, mas um comando quebrado é fácil de copiar errado. Divida comandos longos com \ no fim da linha (uma crase, `, no PowerShell) ou reduza o tamanho da fonte.
Tabelas largas. As colunas se estreitam até caber na página, e as linhas nunca são divididas entre páginas. Reduza a fonte para 9 ou 10 pt, escolha margens estreitas, abrevie os cabeçalhos ou divida a tabela em duas. O painel Estilo não oferece orientação paisagem.
Um diagrama Mermaid aparece como texto vermelho. É a mensagem de erro do Mermaid: o código do diagrama tem um erro de sintaxe.

Tudo roda no seu navegador: o Markdown nunca é enviado, o que importa para documentação interna. Para ver todos os elementos que o editor suporta, consulte o guia de Markdown.