mdq - jq para Markdown

 (github.com/yshavit)
7 puntos por GN⁺ 2025-02-24 | 1 comentarios | Compartir por WhatsApp
  • mdq es una herramienta que ayuda a encontrar fácilmente partes específicas dentro de documentos Markdown
  • Es útil para revisar plantillas o checklists en documentos Markdown como los PR de GitHub
    • Por ejemplo, se puede usar el comando mdq '- [ ]' para encontrar tareas no completadas

Uso básico

  • Seleccionar la sección que contiene "usage": cat example.md | mdq '# usage'
  • Se pueden encadenar filtros: cat example.md | mdq '# usage | -'
  • Verificar que se hayan buscado issues existentes antes de enviar un reporte de bug: mdq -q '- [x] I have searched for existing issues'
  • Extraer tickets de referencia: cuando un PR menciona un ticket, se pueden extraer los enlaces del Markdown como JSON y obtener la URL con jq.
    TICKET_URL="$(echo "$PR_TEXT" | mdq --output json '# Ticket | [](^https://tickets.example.com/[A-Z]+-\d+$)' | jq -r '.items[].link.url')"
  • Reducir tablas grandes: se pueden filtrar tablas para encontrar el calendario de guardias de una fecha o persona específica.
    • Encontrar las fechas de guardia de Alice: cat oncall.md | mdq ':-: /On-Call|Alice/:-: *'
    • Encontrar quién está de guardia en la semana del 15 de enero de 2024: cat oncall.md | mdq ':-: * :-: 2024-01-15'

Lecturas relacionadas

1 comentarios

 
GN⁺ 2025-02-24
Comentarios de Hacker News

  • Los PR de GitHub son documentos Markdown, y algunas organizaciones usan plantillas específicas que incluyen listas de verificación que todos los revisores deben completar

    • Para hacer cumplir este tipo de funcionalidad, hay que usar expresiones regulares complejas, que son difíciles de escribir y aún más difíciles de depurar
    • GitHub está enfocado en la IA en lugar de desarrollar la funcionalidad necesaria
    • Bitbucket ofrece una función para bloquear PR usando una lista de casillas de verificación fuera del cuadro de descripción
    • Hay una mejor manera de resolver este problema; puedes ver el primer ejemplo en el README del OP
    • Es un gran proyecto, y como últimamente escribo principalmente MDX, estaría bien ver soporte para ese dialecto

  • Una de las razones por las que los formatos de archivo basados en texto como Markdown se hicieron populares fue que se podían analizar con expresiones regulares y gestionar con control de versiones

  • Mi flujo de trabajo pasa por el JSON AST de Pandoc y luego usa Jq

    • Esto también funciona con otros formatos de entrada

  • Gracias por compartirlo, le echaré un vistazo

    • Quería algo parecido

  • Después de probar varias cosas, el único "sistema de notas" que sigo usando es un directorio de archivos Markdown que se hacen commit automáticamente a git cuando cambian

  • Quería agregar algunas funciones inteligentes para poder dar seguimiento al trabajo

    • Por ejemplo, limpiar tareas completadas, mover tareas incompletas al diario del día siguiente y recopilar tareas desde "proyectos", entre otras cosas
    • Para eso empecé a escribir algo de código en Rust usando markdown-rs
    • Para hacer round-trip de Markdown junto con los cambios, hoy por hoy solo es compatible con la versión en JavaScript de la librería que serializa Markdown con estilo de GitHub
    • Así que hice una prueba de concepto volcando el AST de Markdown a JSON en Rust y serializándolo en JavaScript
    • markdown-rs guarda información de posición, pero no guarda información de los tokens fuente
    • Por lo tanto, no es posible hacer un round-trip confiable

  • Quería tratar los documentos Markdown como árboles

    • Quería usar un lenguaje tipo xpath para extraer secciones con base en headings
    • De cualquier forma, voy a revisar el código; gracias por publicarlo

  • MarkdownDB ofrece un backend de SQLite para archivos Markdown

    • Siento que la estructura de los archivos .md no siempre se respeta ni se considera como objetivo de serialización de datos

  • Gracias por compartirlo; por ahora no tengo un caso de uso inmediato, pero está bueno saber que existe algo así

  • Quería mencionar una pequeña observación sobre las llamadas de shell documentadas

    • Por ejemplo, cat example.md | mdq '# usage' podría cambiarse por redirección de archivo a stdin para evitar invocar el proceso innecesario de cat
    • De forma similar, echo "$ISSUE_TEXT" | mdq -q '- [x] I have searched for existing issues' también puede evitar el proceso innecesario de echo

  • Estaría bien agregar ejemplos más realistas al README

    • Eso ayudaría a la gente que no identifica de inmediato para qué sirve

  • Algo interesante que aprendí investigando herramientas y librerías existentes es que muchas serializan Markdown a HTML antes de ejecutar extracción o manipulación estructurada

    • Como Markdown fue diseñado para serializarse a HTML, un documento Markdown/AST principalmente no tiene estructura de árbol
    • Más bien, es un arreglo de elementos en el orden en que aparecen en el documento
    • Solo las listas y las citas en bloque admiten anidación
    • Por ejemplo, h1 -> párrafo -> h2 -> párrafo no está anidado, sino que es un arreglo de cuatro elementos ordenados
    • Si pruebas implementarlo con HTML en Cursor o Copilot, probablemente podrás desarrollarlo más rápido

  • Siento que encontré esta herramienta justo en el momento en que la necesitaba

    • Será perfecta para una tarea específica

  • Gracias a Yuval por compartir esta herramienta y por usar una licencia permisiva, lo que permite usarla en el trabajo