Notation

¿Qué es Notation?

Notation es una herramienta que te permite escribir documentación en Markdown y publicarla automáticamente en Notion. Esto te permite aprovechar las capacidades de IA de Notion, la funcionalidad de búsqueda y las opciones de formato para tu documentación. Simplifica la gestión de la documentación manteniéndola cerca del código y agiliza el proceso de publicación.

¿Cómo usar Notation?

1. Escribe tu documentación en Markdown.
2. Crea una página de Notion para alojar tu documentación.
3. Obtén una clave API de Notion.
4. Coloca la clave API en un archivo ~/.notation/Notation.toml.
5. Ejecuta notation ship --src </path/to/you/docs>.
6. Visualiza tu documentación en Notion con búsqueda y formato de IA.

Características principales:

• Soporte de Markdown: Escribe documentación utilizando la sintaxis estándar de Markdown.
• Publicación automática: Publica fácilmente tu documentación Markdown en Notion.
• Integración de Notion: Aprovecha las capacidades de IA, búsqueda y formato de Notion.
• Implementación flexible: Mantén la documentación interna, publícala como una página de Notion o impleméntala como un sitio web completo utilizando herramientas como Super.so.
• intro.md: Envía contenido a la página principal directamente utilizando un archivo intro.md.
• Argumentos: Establece el título y el emoji de la página a través de indicadores CLI en tu archivo Markdown.

¿Por qué es importante Notation?

Notation aborda varios puntos débiles en la gestión de la documentación:

• Mantiene la documentación cerca del código, promoviendo un mejor mantenimiento.
• Evita la necesidad de servicios de documentación separados.
• Simplifica el proceso de publicación.
• Permite el uso de las potentes funciones de Notion para la documentación.

Configuración:

Para configurar Notation, crea un archivo Notation.toml junto al binario de notation (normalmente en ~/.notation/).

## ~/.notation/Notation.toml

[notion]
secret = ""
## este es el título de la página que alojará tu nueva documentación
parent_page = ""

Crea una cuenta de Notion, crea una página para alojar tu documentación y configura la integración para empezar. Las instrucciones detalladas están disponibles en la documentación completa. Esto facilita que cualquiera contribuya y mantenga la documentación.

¿Dónde puedo usar Notation?

Notation es ideal para:

• Proyectos de software que requieren documentación clara y mantenible.
• Equipos que utilizan Notion para la gestión interna del conocimiento.
• Personas que prefieren Markdown para escribir documentación.

¿Cuál es la mejor manera de usar Notation?

Para aprovechar al máximo Notation, asegúrate de que tus archivos Markdown estén bien estructurados y organizados. Utiliza la función intro.md para añadir contenido directamente a la página principal. Aprovecha las funciones de IA y búsqueda de Notion para mejorar la capacidad de descubrimiento.