Notation
Kristian Gaylord · Programação · Aprendizado
Notation é uma ferramenta de linha de comando gratuita e de código aberto que publica uma pasta de arquivos Markdown no Notion. Você escreve a documentação no repositório, roda um comando e o Notion entrega tudo com busca e recursos de IA.
Sobre Notation
About
O que é o Notation
O Notation é um utilitário de terminal que pega um diretório cheio de arquivos Markdown e joga o conteúdo em uma página do Notion. O projeto é escrito em Rust e distribuído sob a licença GPL-3.0. Um comando, notation ship --src, lê a pasta e remonta a árvore de páginas dentro do Notion.
A ideia por trás é direta: documentação pertence ao código que ela descreve. Você edita os .md no mesmo pull request da funcionalidade, quem revisa enxerga o diff e a integração contínua pode rodar a publicação. Ninguém precisa abrir outro serviço depois do merge.
Dois limites definem o uso. O Notion é o único destino, então a publicação sempre cai em uma página sua. E a sincronização vai em uma direção só, de Markdown para o Notion, o que mantém o repositório como fonte da verdade e deixa claro que o que for digitado no Notion não volta.
Como começar
- Instale o binário com o script de shell da página do projeto. Ele coloca o executável em
~/.notatione cria um arquivo de configuração inicial ao lado. - Crie no Notion a página que vai abrigar a documentação e dê a ela um nome que você consiga repetir exatamente na configuração.
- Gere uma integração interna em Configurações e membros e copie o segredo. Na página principal, adicione essa integração em Conexões para liberar a escrita.
- Abra
~/.notation/Notation.tomle preencha dois valores: osecretda integração e o título deparent_page. - Rode
notation ship --src /caminho/para/docsdentro do repositório. Confira o resultado no Notion e, se quiser um site público, compartilhe a página ou aponte um domínio próprio para ela.
Informações do produto
Uma visão rápida dos preços, das plataformas compatíveis e do desempenho de Notation.
Ideal para
Os usuários, tarefas e cenários em que esta ferramenta se encaixa melhor.
Usuários
- Engenheiros de backend e plataforma
- Times de produto pequenos, sem site de documentação
- Pessoas de suporte, vendas e produto
Tarefas
- Publicar referências de API
- Atualizar guias de onboarding
- Transformar runbooks internos em wiki
Cenários
- Você já paga o Notion e não quer outra assinatura de documentação. O Notation acrescenta só a etapa de publicação.
- A documentação ficou para trás porque atualizá-la exigia visitar outra ferramenta. Trazer a fonte para o repositório acaba com esse desvio.
- Você quer documentação revisada como código. Como os arquivos são texto puro sob controle de versão, o fluxo normal de pull request já cobre isso.
Principais recursos
Publicar uma pasta com um comando
notation ship --src percorre o diretório de origem e grava cada arquivo na página configurada do Notion. Não há build nem site gerado para publicar, então entre o merge e o conteúdo no ar existe apenas um comando.
A estrutura de pastas vira estrutura de páginas
Diretórios se tornam subpáginas e subdiretórios viram subpáginas de segundo nível, então a árvore que você vê no editor é a mesma que o leitor vê no Notion. Ao renomear uma pasta, a página correspondente muda de nome na próxima publicação.
intro.md para a página principal
Um arquivo chamado intro.md na raiz da pasta grava o conteúdo direto na página pai, sem criar uma página filha. A seção ganha uma capa com texto, links e contexto em vez de um contêiner vazio com uma lista de filhos.
Título e emoji por página
Dois marcadores no topo de cada arquivo Markdown, --title e --emoji, definem o nome e o ícone da página no Notion. Um arquivo chamado setup.md pode aparecer como "Getting Started" com um foguete, então os nomes de arquivo continuam práticos para a máquina e os títulos ficam agradáveis para quem lê.
Wiki interno ou site público
O mesmo destino pode ficar privado dentro do workspace ou ser compartilhado como site aberto. Para usar domínio próprio, a documentação oficial indica o Super como camada de front end, que é como o próprio notation.so é servido.
Busca, IA e formatação do Notion sem custo extra
Quando o conteúdo chega ao Notion, você herda o índice de busca, as respostas com IA, o sumário e a formatação por blocos. Buscar em um conjunto grande de documentação Markdown é um problema difícil, e aqui quem resolve é outra pessoa.
Prós e contras
Prós
- Gratuito e de código aberto sob GPL-3.0, sem assentos, planos ou limite por página para acompanhar.
- A documentação fica no repositório, então revisão de código, branches e integração contínua valem para ela sem configuração extra.
- A instalação é curta: baixar o binário, criar uma integração no Notion e preencher dois valores.
- Quem lê trabalha no Notion, e assim busca, comentários e respostas de IA vêm junto com a ferramenta que o time já deixa aberta.
- O resultado parece feito à mão no Notion, então um leitor sem perfil técnico não percebe que as páginas nasceram de Markdown.
Contras
- A sincronização é de mão única. O que for editado dentro do Notion é sobrescrito na publicação seguinte, então o repositório precisa continuar sendo o único lugar onde se escreve.
- Imagens exigem URL pública, porque arquivos locais não são enviados. Você hospeda o arquivo em outro lugar e cola o link.
- Cada pessoa precisa de conta no Notion, de uma página hospedeira e de um token de integração interna: três pontos para errar antes da primeira execução bem-sucedida.
- O projeto é pequeno e o último commit é de agosto de 2024. Uma mudança incompatível na API do Notion exigiria alguém corrigir o binário, e o instalador não funciona no Windows.
Perguntas frequentes
Serve para publicar Markdown para Notion de uma vez. Você mantém os arquivos .md em um repositório, roda notation ship e eles aparecem como uma árvore de páginas dentro de uma página do Notion que você escolher.
Conteúdo relacionado
Explore ferramentas, skills e artigos relacionados a Notation.
Alternativas a Notation
Base Code
Base44 (Wix) · Programação · ProdutividadeO Base Code é um ambiente de desenvolvimento em nuvem compartilhado da Base44. O time descreve mudanças em um repositório do GitHub pelo chat, confere tudo na prévia e envia o resultado como pull request.
Google EmbeddingGemma 2
Google DeepMind · Escrita · Imagem · ProgramaçãoGoogle EmbeddingGemma 2 é um modelo aberto de 740 milhões de parâmetros que transforma texto, código, imagens, áudio e quadros de vídeo em vetores de um único espaço de 768 dimensões, rodando em celulares e notebooks.
GitGlow
GitGlow · Programação · ProdutividadeO GitGlow é um cliente Git de desktop que coloca seu código e as mudanças dos seus agentes de IA na mesma revisão, para você saber o que vai sair da máquina antes de publicar.