O GitHub revolucionou a maneira como escrevemos READMEs. Até mesmo a função e importância desses arquivos mudou, para melhor.

É comum ver READMEs sendo usados como documentação de projetos, oferecer detalhes técnicos, exemplos de utilização, instruções de instalação e muito mais. A chamada GitHub Flavored Markdown, permite criar, muito facilmente, READMEs bem estruturados e elegantes.

Dependendo do tamanho do seu README (ou qualquer outro arquivo markdown), pode ser interessante apresentar todas essas informações de maneira mais estruturada, com links para as diferentes seções e um layout mais adequado.

A princípio, isso pode parecer uma tarefa muito complicada, mas não é!!!!

Flatdoc

Flatdoc é um projeto open source, desenvolvido em JavaScript, que utiliza a API do GitHub para acessar um determinado arquivo Markdown, no seu repositório, e renderizar um site completo, diretamente no cliente (é JavaScript!!), sem necessidade de nenhum processamento no servidor, nem toneladas de configurações e muito menos lidar com HTML e CSS (ufa!).

A página do projeto é um ótimo exemplo do uso desta ferramenta!

O Flatdoc é perfeito para usar com o gh-pages e com apenas um commit é possível ter sua documentação online. As instruções de utilização estão disponíveis no site do projeto e se restringem a copiar e colar o template e algumas poucas linhas de código JavaScript.

Agora corre pra configurar o Flatdoc naquele seu super projeto e volta pra mostrar como ficou! :D