mdq - jq pour Markdown

 (github.com/yshavit)
7 points par GN⁺ 2025-02-24 | 1 commentaires | Partager sur WhatsApp
  • mdq est un outil qui permet de trouver facilement des parties spécifiques dans des documents Markdown
  • Utile pour vérifier certains modèles ou check-lists dans des documents Markdown comme les PR GitHub
    • Par exemple, pour trouver des tâches non terminées, on peut utiliser la commande mdq '- [ ]'

Utilisation de base

  • Sélectionner la section contenant "usage" : cat example.md | mdq '# usage'
  • Les filtres peuvent être chaînés : cat example.md | mdq '# usage | -'
  • Vérifier qu'une recherche d'issues existantes a bien été effectuée avant de soumettre un bug report : mdq -q '- [x] I have searched for existing issues'
  • Extraire un ticket de référence : lorsqu'une PR mentionne un ticket, il est possible d'extraire les liens du Markdown en JSON puis d'obtenir l'URL avec jq.
    TICKET_URL="$(echo "$PR_TEXT" | mdq --output json '# Ticket | [](^https://tickets.example.com/[A-Z]+-\d+$)' | jq -r '.items[].link.url')"
  • Réduire de grands tableaux : il est possible de filtrer un tableau pour trouver l'astreinte d'une date donnée ou d'une personne donnée.
    • Trouver les dates d'astreinte d'Alice : cat oncall.md | mdq ':-: /On-Call|Alice/:-: *'
    • Trouver la personne d'astreinte pour la semaine du 15 janvier 2024 : cat oncall.md | mdq ':-: * :-: 2024-01-15'

À lire aussi

1 commentaires

 
GN⁺ 2025-02-24
Avis Hacker News

  • Les PR GitHub sont des documents Markdown, et certaines organisations utilisent des modèles spécifiques incluant une checklist que tous les reviewers doivent compléter

    • Pour imposer ce type de fonctionnalité, il faut utiliser des expressions régulières complexes, difficiles à écrire et encore plus à déboguer
    • GitHub se concentre sur l’IA au lieu de développer les fonctionnalités nécessaires
    • Bitbucket propose une fonctionnalité permettant de bloquer une PR à l’aide d’une liste de cases à cocher en dehors du champ de description
    • Il existe une meilleure façon de résoudre ce problème, visible dans le premier exemple du README de l’OP
    • Beau projet, et comme j’écris surtout en MDX ces jours-ci, ce serait bien de voir une prise en charge de ce dialecte

  • L’une des raisons pour lesquelles des formats de fichiers textuels comme Markdown ont gagné en popularité est qu’ils pouvaient être analysés avec des expressions régulières et gérés via le contrôle de version

  • Mon workflow passe par l’AST JSON de Pandoc, puis utilise Jq

    • Cela fonctionne aussi avec d’autres formats d’entrée

  • Merci du partage, je vais y jeter un œil

    • C’est le genre de chose que je cherchais

  • Après avoir essayé plusieurs options, le seul « système de notes » que je continue à utiliser est un répertoire de fichiers Markdown automatiquement commités dans git à chaque modification

  • Je voulais ajouter quelques fonctionnalités intelligentes pour suivre les tâches

    • Par exemple, nettoyer les tâches terminées, reporter les tâches non terminées dans le journal du lendemain, et regrouper les tâches par « projet », etc.
    • J’ai commencé à écrire du code Rust avec markdown-rs pour cela
    • Pour faire du round-trip sur le Markdown avec les modifications, seule la version JavaScript de la bibliothèque prend actuellement en charge la sérialisation du Markdown au style GitHub
    • J’ai donc fait une preuve de concept en dumpant l’AST Markdown en JSON depuis Rust, puis en sérialisant en JavaScript
    • markdown-rs conserve les informations de position, mais pas les informations sur les tokens source
    • Il est donc impossible de faire un round-trip fiable

  • Je voulais traiter les documents Markdown comme des arbres

    • Je voulais utiliser un langage de type xpath pour extraire des sections à partir des titres
    • Quoi qu’il en soit, je vais aller voir le code, merci de l’avoir publié

  • MarkdownDB fournit un backend SQLite pour les fichiers Markdown

    • J’ai l’impression que la structure des fichiers .md n’est pas toujours respectée ni prise en compte comme cible de sérialisation de données

  • Merci du partage, je n’ai pas de cas d’usage immédiat pour le moment, mais c’est bien de savoir que ce genre d’outil existe

  • Je voulais signaler un petit point sur les appels shell documentés

    • Par exemple, cat example.md | mdq '# usage' pourrait être remplacé par une redirection de fichier vers stdin afin d’éviter de lancer un processus cat inutile
    • De même, echo "$ISSUE_TEXT" | mdq -q '- [x] I have searched for existing issues' pourrait éviter un processus echo inutile

  • Ce serait bien d’ajouter des exemples plus réalistes dans le README

    • Cela aiderait les personnes pour qui les cas d’usage ne sont pas immédiatement évidents

  • Une chose intéressante que j’ai apprise en étudiant les outils et bibliothèques existants, c’est que beaucoup sérialisent d’abord le Markdown en HTML avant d’effectuer une extraction/manipulation structurée

    • Comme Markdown est conçu pour être sérialisé en HTML, un document Markdown / AST n’est généralement pas une structure en arbre
    • C’est plutôt un tableau d’éléments dans l’ordre où ils apparaissent dans le document
    • Seules les listes et les citations en bloc prennent en charge l’imbrication
    • Par exemple, h1 -> paragraphe -> h2 -> paragraphe n’est pas imbriqué, mais forme un tableau de quatre éléments ordonnés
    • En demandant à Cursor ou Copilot de tester une implémentation utilisant du HTML, il serait peut-être possible de développer plus vite

  • J’ai l’impression d’avoir découvert cet outil exactement au moment où j’en avais besoin

    • Il conviendra parfaitement à une tâche spécifique

  • Merci à Yuval d’avoir partagé cet outil, et merci d’avoir choisi une licence permissive, ce qui me permet de l’utiliser au travail