Vale, el linter de prosa que revisa documentación como si fuera código
La herramienta, un binario de Go sin runtime aparte, aplica reglas en YAML a Markdown, AsciiDoc, comentarios de código y descripciones OpenAPI. Acumula 13,9 millones de descargas.
Cualquiera que haya montado un pipeline conoce los linters de código. Vale hace lo mismo, pero con la prosa: revisa la documentación de un proyecto con reglas declaradas en YAML y avisa cuando aparece un término no permitido, una inconsistencia de estilo o una frase que no sigue la guía del equipo. Es un único binario escrito en Go, sin runtime aparte, y se distribuye para macOS, Windows y Linux.
El proyecto no se queda en ficheros Markdown. Vale parsea primero el marcado y aplica reglas distintas según el contexto: encabezados, listas, celdas de tabla. Los bloques de código y las URLs quedan fuera para no generar falsos positivos. Soporta doce formatos de marcado —Markdown, AsciiDoc, reStructuredText, MDX, MyST, Quarto, Typst, HTML, XML, DITA, Org y QDoc— y extrae comentarios de diecinueve lenguajes con gramáticas de tree-sitter, revisando el Markdown que haya dentro. Un comentario dentro de una cadena de texto sigue siendo código y no se toca.
También prosa que no está en documentos
Hay una figura, las Views, que selecciona la escritura dentro de ficheros estructurados. Sirve para validar la descripción de una API en OpenAPI, el contenido de una celda de Jupyter, mensajes de commit, transcripciones o docstrings con las reglas propias de cada contexto.
En rendimiento, el dato que da el propio proyecto es una ejecución sobre la documentación de GitLab: 2.827 páginas Markdown, 82 reglas aplicadas, menos de 20 segundos. La cifra es suya, no de un tercero.
Cómo se adopta
La configuración vive en un .vale.ini dentro del repositorio, de modo que todo el equipo ejecuta las mismas comprobaciones. Los estilos se sincronizan con vale sync y hay paquetes publicados por Microsoft, Google y Red Hat que se pueden tomar como base. Las reglas propias se escriben en YAML con sustituciones, niveles de aviso y mensajes. Para integración continua existe una GitHub Action que ya usan 4.200 repositorios.
Los números de distribución están repartidos. GitHub Releases acumula 11,4 millones de descargas; Docker Hub, 2,3 millones; conda-forge, 165.400; Chocolatey, 19.500. PyPI suma 1,6 millones en los últimos seis meses a través de un wrapper mantenido por la comunidad, y npm, 139.800 en el último mes. Homebrew registra 76.600 en doce meses. En total, 13,9 millones contando solo los canales que publican un acumulado histórico. El repositorio tiene 6.100 estrellas y 64 contribuidores, y la herramienta también llega por WinGet y la Snap Store.
Vale no es nuevo, pero su combinación de un solo binario, reglas en YAML y cobertura amplia de formatos lo ha colocado como pieza habitual en equipos que mantienen mucha documentación. Para quien no lo tenga en el pipeline, la pregunta es cuánto tiempo dedica a revisar a mano lo que un puñado de reglas puede comprobar en cada commit.
