Como criar um README dinâmico usando Javascript

Olá! Você já pensou como seria poder gerar um README dinamicamente para aquele seu projeto do GitHub?
Eu já, mas nunca pensei em como funcionaria... até eu pesquisar se era possível e acabar me surpreendendo.

Depois de algumas pesquisas descobri uma feature do GitHub chamada "GitHub Actions", e ela consegue executar um código que você especificar, em diversas situações como: após um push, pull-request, e até mesmo em um intervalo especificado. Isso era justamente o que eu precisava, e com essa feature em mãos comecei a escrever meu Javascri- calma...

...Como isso é um guia, melhor eu documentar como fiz e como você também pode fazer e utilizar de diversas maneiras como quiser. Então vamos começar pelo começo:

1. Criando uma base

Gerar um markdown direto do Javascript não é tão prático assim, pois para visualizar você precisaria executar o Javascript, e repetir isso para cada mudança definitivamente não é viável a longo prazo (vamos ignorar o nodemon). Por isso eu recomendo criar um arquivo base em markdown, e modificá-lo usando Javascript, ao invés de gerá-lo por completo.

Como exemplo, vou criar um novo repositório no GitHub e disponibilizarei ao final do blog. Então vamos começar por essa base em markdown (que nomeei como "readme_base"), definindo nela as informações que serão fixas, e quais serão geradas:

# %{titulo} Eu coloquei o titulo dentro de `%{}` apenas para evitar que haja alguma ambiguidade com textos comuns. Todas as partes desta base podem ser manipuladas e modificadas, por exemplo aqui eu irei inserir uma lista de nomes: %{listaDeNomes}} 

2. Modificando a base

Para testamos se está tudo funcionando, vamos criar um arquivo em Javascript, no qual nomearei como "index.js", para modificar a base:

/* o fs é quem irá ler o arquivo e gerar um novo, ele vem por padrão no node, então não se preocupe */ const fs = require('fs') // esta parte lê o arquivo "README_BASE" fs.readFile('README_BASE.md', 'utf-8', (err, data) => { if (err) { throw err; } /* aqui é onde acontecem as substituições, por exemplo substituindo %{titulo} por "Dynamic Readme" */ const substituicoes = { titulo: 'Dynamic Readme', listaDeNomes: `- Carlos\n- Ana\n- Sérgio` } /* aqui é o que verifica e executa as substituições, um regex bem simples com object literals, não precisa mexer aqui */ const modificado = data .replace( /%{.*}/gm, e => substituicoes?.[e.slice(2, -1)] || e ) /* após ter feito as mudanças ele cria um arquivo chamado "README.md" com a nova versão */ fs.writeFile('README.md', modificado, 'utf-8', (err) => { if (err) { throw err; } console.log('✔ Processo finalizado!'); }); }); 

Este código será executado via node, então sinta-se livre para adicionar o que quiser, sejam pacotes, requisições em apis, gerar imagens, está em suas mãos.

3. Automatizando o processo

"Mas isso apenas gerou o arquivo pois fui eu quem iniciou o javascript, então para executar esse processo automaticamente eu precisaria de um host?"

Felizmente não, pois no caso do GitHub ele disponibiliza o github actions no qual eu havia falado. Ela permite que o processo rode em diversas circunstâncias, e no caso deste exemplo usarei o schedule que permite que o código seja executado a cada intervalo especificado.

Para isso iremos criar uma pasta chamada .github, e dentro dela uma outra chamada workflows, com um arquivo main.yaml.
Resumindo: .github/workflows/main.yaml.

No arquivo main.yaml é onde diremos ao github quando, como e o quê rodar.

# Nome do processo name: Update automático on: schedule: # cron é o "intervalo" de execução, recomendo usar # o site crontab.guru para lhe ajudar a definir. # nesse caso aqui, ele irá rodar a cada 10 minutos. - cron: '*/10 * * * *' # Aqui vem os passos que a ação segue jobs: build: # Inicia uma máquina virtual ubuntu runs-on: ubuntu-latest # Checa o código atual do repositório steps: - name: Checkout repo uses: actions/checkout@v2 # Instala o node na versão 16.10 - name: Use Node.js uses: actions/setup-node@v1 with: node-version: 16.10 - run: npm install - run: npm run build --if-present env: CI: true # Aqui em index.js você insere # o nome do seu arquivo javascript - name: Roda o arquivo run: |- node index.js cat README.md # E no final commita e faz um push caso haja alguma diferença # comparada ao código atual do repositório - name: Commit e push run: |- git diff git config --global user.email "bot-readme@example.com" git config --global user.name "bot automático" git add -A git commit -m "Arquivo atualizado!" || exit 0 git push 

Com isso feito, sua pasta/repositório deve estar mais ou menos assim:

> .github > workflows > main.yaml > index.js > readme_base.md > README.md (gerado) 

Se estiver assim, perfeito, tá tudo certo. Casos os nomes estejam diferentes ou não tenha gerado o README ainda, tá tudo bem também.

Mas só avisando que caso você mande tudo pro GitHub, e em 10 minutos seu repositório não atualize, calma. O GitHub Actions nem sempre é imediato, algumas vezes leva mais tempo do que o especificado. Por exemplo no meu teste desse repositório, apesar de eu especificar 10 minutos levou 25 😅.

Você pode acompanhar as actions por aqui, sempre que uma for executada ela irá aparecer:

E falando no repositório, aqui está o link pra ele: Dynamic Readme. Se quiser pode fazer um fork e modificar ou seguir este tutorial, como preferir.

4. O final

Opa! Gostou do blog? É o meu primeiro, mas tentei deixar ele completo e simples de se entender, espero ter conseguido ^^.

E não pensa que dá pra fazer só essas coisinhas de trocar texto por texto não! No meu readme eu fiz uma seção que atualiza mostrando minhas atividades mais recentes, e até gera uma imagem utilizando a api do github para pegar um seguidor aleatório meu!

Tô ansioso pra ver o que vocês também conseguem criar.
Me marca no Twitter caso faça algo bacana com isso. 'Inté!