Notation
Kristian Gaylord · Programación · Aprendizaje
Notation es una herramienta de línea de comandos gratuita y de código abierto que publica una carpeta de archivos Markdown en Notion. Escribes la documentación en el repositorio, ejecutas un comando y Notion la sirve con búsqueda y funciones de IA.
Acerca de Notation
About
Qué es Notation
Notation es una utilidad de terminal que toma un directorio lleno de archivos Markdown y lo vuelca en una página de Notion. Está escrita en Rust y se distribuye con licencia GPL-3.0. Un solo comando, notation ship --src, lee la carpeta y reconstruye el árbol de páginas dentro de Notion.
La lógica detrás es simple: la documentación pertenece al código que describe. Editas los .md en el mismo pull request que la funcionalidad, quien revisa ve el diff y la integración continua puede ejecutar la publicación. Nadie tiene que entrar a un servicio aparte después de fusionar una rama.
Hay dos límites que definen su uso. Notion es el único destino, así que siempre publicas sobre una página tuya. Y la sincronización va en una sola dirección, de Markdown hacia Notion, de modo que el repositorio manda y lo que se escriba dentro de Notion no regresa.
Primeros pasos
- Instala el binario con el script de shell de la página del proyecto. Deja el ejecutable en
~/.notationy crea un archivo de configuración base al lado. - Crea en Notion la página que alojará la documentación y ponle un nombre que puedas repetir tal cual en la configuración.
- Genera una integración interna en Ajustes y miembros, y copia su secreto. En la página principal, añade esa integración desde Conexiones para darle permiso de escritura.
- Abre
~/.notation/Notation.tomly rellena dos valores: elsecretde la integración y el título deparent_page. - Ejecuta
notation ship --src /ruta/a/docsdesde el repositorio. Revisa el resultado en Notion y, si quieres un sitio público, comparte la página o apunta un dominio propio hacia ella.
Información del producto
Un vistazo rápido a los precios, las plataformas compatibles y el rendimiento de Notation.
Ideal para
Los usuarios, tareas y casos de uso en los que esta herramienta encaja mejor.
Usuarios
- Ingenieros de backend y plataforma
- Equipos de producto pequeños sin sitio de documentación
- Personal de soporte, ventas y producto
Tareas
- Publicar referencias de API
- Actualizar guías de incorporación
- Convertir runbooks internos en un wiki
Casos de uso
- Ya pagas Notion y no quieres otra suscripción de documentación. Notation añade el paso de publicación y nada más.
- Tu documentación se quedó atrás porque actualizarla exigía entrar a otra herramienta. Mover el origen al repositorio elimina ese viaje.
- Quieres que la documentación pase por revisión como el código. Al ser texto plano bajo control de versiones, el flujo normal de pull request la cubre.
Funciones clave
Publicar una carpeta con un comando
notation ship --src recorre el directorio de origen y escribe cada archivo en la página de Notion configurada. No hay compilación ni sitio generado que desplegar, así que entre fusionar un cambio y verlo publicado media un comando.
La estructura de carpetas se vuelve estructura de páginas
Los directorios se convierten en subpáginas y los subdirectorios en subpáginas de segundo nivel, de modo que el árbol que ves en el editor es el que ve el lector en Notion. Al renombrar una carpeta, la página correspondiente cambia de nombre en la siguiente publicación.
intro.md para la página principal
Un archivo llamado intro.md en la raíz de la carpeta escribe su contenido directamente en la página padre en lugar de crear una página hija. Así la sección tiene una portada con texto, enlaces y contexto, no un contenedor vacío con una lista de hijos.
Título y emoji por página
Dos indicadores al inicio de cada archivo Markdown, --title y --emoji, fijan el nombre y el icono de la página en Notion. Un archivo llamado setup.md puede aparecer como «Getting Started» con un cohete, así que los nombres de archivo siguen siendo cómodos para la máquina y los títulos se leen bien.
Wiki interno o sitio web público
El mismo destino puede quedarse privado dentro del espacio de trabajo o compartirse como sitio público. Para usar un dominio propio, la documentación oficial remite a Super como capa frontal, que es como se sirve notation.so.
Búsqueda, IA y formato de Notion sin coste extra
Cuando el contenido llega a Notion, heredas su índice de búsqueda, sus respuestas con IA, la tabla de contenidos y el formato por bloques. La búsqueda sobre un conjunto grande de documentación Markdown es un problema difícil, y aquí lo resuelve otro.
Ventajas y desventajas
Ventajas
- Gratis y de código abierto bajo GPL-3.0, sin asientos, niveles ni límites por página que vigilar.
- La documentación se queda en el repositorio, así que la revisión de código, las ramas y la integración continua se aplican sin trabajo extra.
- La puesta en marcha es corta: instalar el binario, crear una integración de Notion y rellenar dos valores.
- Quien lee trabaja en Notion, con lo que la búsqueda, los comentarios y las respuestas de IA vienen con la herramienta que el equipo ya tiene abierta.
- El resultado parece hecho a mano en Notion, así que un lector sin perfil técnico no nota que las páginas se generaron desde Markdown.
Desventajas
- La sincronización es de ida. Lo que se edite dentro de Notion se sobrescribe en la siguiente publicación, así que el repositorio tiene que seguir siendo el único lugar donde se escribe.
- Las imágenes necesitan una URL pública porque los archivos locales no se suben. Alojas el recurso en otro sitio y pegas el enlace.
- Cada persona necesita cuenta de Notion, una página anfitriona y un token de integración interna: tres puntos donde equivocarse antes de la primera ejecución correcta.
- El proyecto es pequeño y su último commit es de agosto de 2024. Un cambio incompatible en la API de Notion exigiría que alguien parchee el binario, y el instalador no admite Windows.
Preguntas frecuentes
Sirve para publicar Markdown a Notion de una vez. Mantienes los archivos .md en un repositorio, ejecutas notation ship y aparecen como un árbol de páginas dentro de una página de Notion que elijas.
Contenido relacionado
Explora herramientas, habilidades y artículos relacionados con Notation.
Alternativas a Notation
Base Code
Base44 (Wix) · Programación · ProductividadBase Code es un entorno de desarrollo en la nube compartido de Base44. El equipo describe cambios sobre un repositorio de GitHub en el chat, los ve en una vista previa y los envía como pull requests.
Google EmbeddingGemma 2
Google DeepMind · Escritura · Imagen · ProgramaciónGoogle EmbeddingGemma 2 es un modelo abierto de 740 millones de parámetros que convierte texto, código, imágenes, audio y fotogramas de vídeo en vectores de un mismo espacio de 768 dimensiones, y funciona en móviles y portátiles.
GitGlow
GitGlow · Programación · ProductividadGitGlow es un cliente Git de escritorio que reúne tu código y los cambios de tus agentes de IA en una sola revisión, para que sepas qué va a salir de tu máquina antes de publicarlo.