Notation

O que é Notation?

Notation é uma ferramenta que permite escrever documentação em Markdown e publicá-la automaticamente no Notion. Isso permite que você aproveite os recursos de IA do Notion, a funcionalidade de pesquisa e as opções de formatação para sua documentação. Simplifica o gerenciamento da documentação, mantendo-a próxima ao código e agiliza o processo de publicação.

Como usar o Notation?

1. Escreva sua documentação em Markdown.
2. Crie uma página do Notion para hospedar sua documentação.
3. Obtenha uma chave de API do Notion.
4. Coloque a chave de API em um arquivo ~/.notation/Notation.toml.
5. Execute notation ship --src </path/to/you/docs>.
6. Visualize sua documentação no Notion com pesquisa e formatação de IA.

Principais recursos:

• Suporte a Markdown: Escreva documentação usando a sintaxe Markdown padrão.
• Publicação automática: Publique facilmente sua documentação Markdown no Notion.
• Integração do Notion: Aproveite os recursos de IA, pesquisa e formatação do Notion.
• Implantação flexível: Mantenha a documentação interna, publique-a como uma página do Notion ou implante-a como um site completo usando ferramentas como Super.so.
• intro.md: Envie conteúdo para a página principal diretamente usando um arquivo intro.md.
• Argumentos: Defina o título e o emoji da página por meio de sinalizadores CLI em seu arquivo Markdown.

Por que o Notation é importante?

Notation aborda vários pontos problemáticos no gerenciamento da documentação:

• Mantém a documentação próxima ao código, promovendo uma melhor manutenção.
• Evita a necessidade de serviços de documentação separados.
• Simplifica o processo de publicação.
• Permite o uso dos poderosos recursos do Notion para documentação.

Configuração:

Para configurar o Notation, crie um arquivo Notation.toml junto com o binário de notation (geralmente em ~/.notation/).

## ~/.notation/Notation.toml

[notion]
secret = ""
## este é o título da página que hospedará sua nova documentação
parent_page = ""

Configure uma conta do Notion, crie uma página para hospedar sua documentação e configure a integração para começar. Instruções detalhadas estão disponíveis na documentação completa. Isso torna mais fácil para qualquer pessoa contribuir e manter a documentação.

Onde posso usar o Notation?

Notation é ideal para:

• Projetos de software que exigem documentação clara e de fácil manutenção.
• Equipes que usam o Notion para gerenciamento interno de conhecimento.
• Indivíduos que preferem Markdown para escrever documentação.

Qual é a melhor maneira de usar o Notation?

Para aproveitar ao máximo o Notation, certifique-se de que seus arquivos Markdown estejam bem estruturados e organizados. Use o recurso intro.md para adicionar conteúdo diretamente à página principal. Aproveite os recursos de IA e pesquisa do Notion para melhorar a capacidade de descoberta.