🇺🇸 English Version

Hello Human 👽! Bem-vindo ao meu repositório 👋

Gere uma bela documentação para os seus repositórios Git

📌 Curta esse repositório para acompanhar atualizações e novidades ( ≖‿ ≖ )

Note

AVISO: Esse repositório está em constante evolução. Se você encontrar algum erro ou tiver sugestões, por favor, abra uma issue ou envie um pull request.

1. Visão Geral
   1.1. Objetivo
   1.2. Contexto e Motivação
2. Implementação
   2.1. Pré-requisitos
   2.2. Instalação
   2.3. Uso
3. Contribuição
4. Versionamento
5. Troubleshooting
6. Show your support

(back to top)

1. Visão Geral

O gtoc é uma CLI escrita em Go que gera e mantém atualizado o sumário (table of contents) de arquivos Markdown. Ele lê os headings do arquivo, monta um índice hierárquico com âncoras compatíveis com o GitHub e insere o resultado entre marcadores HTML, de forma idempotente: rodar o comando duas vezes produz o mesmo resultado.

1.1. Objetivo

Eliminar a manutenção manual de sumários em READMEs e documentações longas. O gtoc cuida de:

• Gerar o índice a partir dos headings reais do arquivo (níveis # a ######);
• Criar âncoras exatamente como o GitHub cria, incluindo acentos (Instalação vira #instalação) e headings duplicados (sufixos -1, -2);
• Ignorar headings dentro de blocos de código e do próprio sumário;
• Atualizar o bloco existente no lugar, preservando o restante do arquivo e as permissões.

1.2. Contexto e Motivação

READMEs bem estruturados facilitam a navegação, mas sumários mantidos à mão ficam desatualizados a cada seção criada ou renomeada. Ferramentas existentes (como o doctoc) resolvem parte do problema, porém este projeto nasceu para: (1) ter uma solução em binário único, sem dependência de Node; (2) tratar corretamente âncoras com acentuação em português; e (3) servir de laboratório de boas práticas de desenvolvimento de CLIs em Go.

(back to top)

2. Implementação

2.1. Pré-requisitos

Nenhum para usar o binário publicado nas releases. Para compilar a partir do código-fonte, é necessário Go 1.25+ (veja a versão exata no go.mod).

2.2. Instalação

Via go install:

go install github.com/lpsm-dev/gtoc@latest

Via binário: baixe o arquivo da sua plataforma na página de releases e coloque-o no seu PATH. Depois de instalado, atualize com o próprio CLI:

gtoc upgrade

Via Docker (build local):

docker build -t gtoc .
docker run --rm -v "$(pwd)":/work gtoc generate README.md

2.3. Uso

Gerar ou atualizar o sumário de um arquivo:

gtoc generate README.md            # atualiza o arquivo no lugar
gtoc generate README.md --dry-run  # só mostra o que seria gerado
gtoc generate README.md --depth 3  # limita a profundidade dos headings
gtoc generate README.md --exclude "rascunho,privado"

O sumário é inserido (e depois atualizado) entre os marcadores abaixo. Na primeira execução sem marcadores, ele é adicionado no início do arquivo:

<!-- START_TABLE_OF_CONTENTS -->
<!-- END_TABLE_OF_CONTENTS -->

Aplicar boas práticas de formatação ao README (marcadores BEGIN_DOCS/END_DOCS, âncora readme-top e links "back to top" ao fim de cada seção #):

gtoc analyze --file README.md

Flags do generate:

Flag	Padrão	Descrição
--file	-	Caminho do arquivo Markdown (ou passe como argumento posicional)
--depth	0	Profundidade máxima de headings (0 = ilimitado)
--exclude	-	Lista de textos de headings a excluir, separados por vírgula (match case-insensitive por substring)
--dry-run	false	Mostra o resultado sem escrever no arquivo
--pretty	false	No dry-run, renderiza o arquivo completo formatado no terminal

Flags globais: --log-level (debug, info, warn, error, fatal), --log-format (text, json) e --log-no-colors.

(back to top)

3. Contribuição

Gostaria de contribuir? Isso é ótimo! Temos um guia de contribuição para te ajudar. Clique aqui para lê-lo.

(back to top)

4. Versionamento

Para verificar o histórico de mudanças, acesse o arquivo CHANGELOG.md.

(back to top)

5. Troubleshooting

Se você tiver algum problema, abra uma issue nesse projeto.

(back to top)

6. Show your support

Dê uma ⭐️ para este projeto se ele te ajudou!

Feito com 💜 pelo Time de DevOps 👋 inspirado no readme-md-generator

(back to top)