Printdown
PT

Transformar um documento do Word em README do GitHub

A documentação muitas vezes nasce no Word: uma especificação escrita pelo time de produto, as notas de instalação de um cliente, um relatório que agora precisa morar ao lado do código. No GitHub, o lugar natural para esse texto é um arquivo README.md, exibido na página inicial do repositório. Redigitar é lento e sujeito a erros. Converter leva um minuto, e alguns ajustes pontuais fazem o resultado parecer escrito para o GitHub desde o início.

1. Prepare o documento do Word

O conversor leva a estrutura do Word para o Markdown, então um documento bem estruturado é convertido de forma limpa. Antes de converter, reserve dois minutos para isto:

  • Use estilos de título (Título 1, Título 2…) em vez de texto grande em negrito. Eles viram cabeçalhos # e ##, e o GitHub os usa para montar o sumário do arquivo.
  • Use listas de verdade (os botões de marcadores e numeração), não hifens digitados à mão.
  • Mantenha as tabelas simples. Tabelas Markdown não mesclam células; uma célula mesclada mantém o texto na primeira coluna.
  • Coloque texto alternativo nas imagens (botão direito → Editar texto alternativo). Ele vira a descrição da imagem no Markdown.

2. Converta para Markdown

Abra o conversor de Word para Markdown e solte seu .docx (arquivos .doc antigos também funcionam). O arquivo é convertido no navegador e nada é enviado, o que é útil para documentos internos.

Se o documento tiver imagens, ative Incluir imagens antes de converter e use Baixar .zip. O zip contém o arquivo Markdown e uma pasta images/, e o Markdown já aponta para images/image-1.png e assim por diante. Sem essa opção, cada imagem é substituída pelo texto alternativo.

Renomeie o arquivo Markdown para README.md e coloque-o, junto com a pasta images/, na raiz do repositório. O GitHub resolve caminhos relativos de imagens, então elas aparecerão na página do repositório.

3. Ajuste o texto para o GitHub

A conversão mantém o texto, títulos, ênfases, listas, tabelas, links e notas de rodapé. O que ela não consegue adivinhar é a intenção: o Word não tem o conceito de bloco de código, e um texto pensado para impressão nem sempre combina com um README. Passe por estes pontos:

  • Um único título. Deixe só um cabeçalho # com o nome do projeto no topo e transforme o resto em ## ou inferior.
  • Blocos de código. Envolva comandos e exemplos em blocos delimitados com a linguagem indicada, para que o GitHub faça o destaque de sintaxe: 
    ```bash
npm install
npm run dev
```
  • Aspas retas no código. O Word troca " e ' por aspas tipográficas (“ ” ‘ ’) e hifens por travessões. Em comandos e código isso quebra o copiar e colar, então substitua.
  • Código em linha para nomes de arquivos, comandos e opções: `config.yml`, `--verbose`.
  • Links relativos. Aponte para outros arquivos do repositório com caminhos como [Como contribuir](CONTRIBUTING.md) em vez de URLs absolutas, para que os links continuem funcionando em forks e branches.
  • Sem sumário manual. O GitHub adiciona um menu de estrutura a todo arquivo Markdown, gerado a partir dos títulos. Um sumário numerado copiado do Word vai ficar desatualizado; remova-o.
  • Diagramas e fórmulas. O GitHub renderiza blocos mermaid como diagramas e LaTeX entre $ como fórmulas, então você pode trocar capturas de fluxogramas simples por um bloco Mermaid mais fácil de manter.

Uma estrutura de README que funciona

Se o documento original não foi escrito como README, reorganize-o em torno do que um visitante precisa primeiro:

  1. Nome do projeto e uma descrição de uma frase.
  2. Uma captura de tela ou um exemplo curto, se ajudar.
  3. Instalação e primeiros passos.
  4. Uso e configuração.
  5. Como contribuir, licença e contato.

Especificações longas podem ir para uma pasta docs/ com link a partir do README.

4. Revise e faça o commit

Cole o README no editor de Markdown para conferir títulos, tabelas e blocos de código na pré-visualização. As imagens da pasta images/ não aparecem ali, porque uma página web não consegue ler arquivos do seu disco, mas aparecerão no GitHub. Quando estiver tudo certo:

git add README.md images/
git commit -m "Adiciona README"
git push

Bônus: o mesmo Markdown serve no caminho inverso. No editor, Baixar PDF gera um PDF caprichado do README para quem prefere um documento a um repositório. O guia de Markdown lista todos os elementos que o editor suporta.

Mais guias