Notation

Qu'est-ce que Notation ?

Notation est un outil qui vous permet d’écrire de la documentation en Markdown et de la publier automatiquement sur Notion. Cela vous permet de tirer parti des capacités d’IA de Notion, de la fonctionnalité de recherche et des options de mise en forme pour votre documentation. Il simplifie la gestion de la documentation en la gardant près du code et rationalise le processus de publication.

Comment utiliser Notation ?

1. Rédigez votre documentation en Markdown.
2. Créez une page Notion pour héberger votre documentation.
3. Obtenez une clé API de Notion.
4. Placez la clé API dans un fichier ~/.notation/Notation.toml.
5. Exécutez notation ship --src </path/to/you/docs>.
6. Affichez votre documentation dans Notion avec la recherche et la mise en forme de l’IA.

Principales caractéristiques:

• Prise en charge de Markdown: Rédigez de la documentation à l’aide de la syntaxe Markdown standard.
• Publication automatique: Publiez facilement votre documentation Markdown sur Notion.
• Intégration de Notion: Tirez parti des capacités d’IA, de recherche et de mise en forme de Notion.
• Déploiement flexible: Conservez la documentation en interne, publiez-la sous forme de page Notion ou déployez-la en tant que site Web complet à l’aide d’outils tels que Super.so.
• intro.md: Envoyez du contenu directement à la page parente à l’aide d’un fichier intro.md.
• Arguments: Définissez le titre et l’emoji de la page via des indicateurs CLI dans votre fichier Markdown.

Pourquoi Notation est-il important ?

Notation résout plusieurs problèmes liés à la gestion de la documentation :

• Garde la documentation près du code, ce qui favorise un meilleur entretien.
• Évite le besoin de services de documentation distincts.
• Simplifie le processus de publication.
• Permet d’utiliser les puissantes fonctionnalités de Notion pour la documentation.

Configuration :

Pour configurer Notation, créez un fichier Notation.toml à côté du binaire de notation (généralement dans ~/.notation/).

## ~/.notation/Notation.toml

[notion]
secret = ""
## c’est le titre de la page qui hébergera votre nouvelle documentation
parent_page = ""

Configurez un compte Notion, créez une page pour héberger votre documentation et configurez l’intégration pour commencer. Des instructions détaillées sont disponibles dans la documentation complète. Cela permet à quiconque de contribuer et de maintenir facilement la documentation.

Où puis-je utiliser Notation ?

Notation est idéal pour :

• Les projets logiciels nécessitant une documentation claire et facile à entretenir.
• Les équipes qui utilisent Notion pour la gestion des connaissances internes.
• Les personnes qui préfèrent Markdown pour rédiger de la documentation.

Quelle est la meilleure façon d’utiliser Notation ?

Pour tirer le meilleur parti de Notation, assurez-vous que vos fichiers Markdown sont bien structurés et organisés. Utilisez la fonctionnalité intro.md pour ajouter du contenu directement à la page parente. Tirez parti des fonctionnalités d’IA et de recherche de Notion pour améliorer la découvrabilité.