mdq – jq für Markdown

 (github.com/yshavit)
7 Punkte von GN⁺ 2025-02-24 | 1 Kommentare | Auf WhatsApp teilen
  • mdq ist ein Tool, das dabei hilft, bestimmte Teile in Markdown-Dokumenten leicht zu finden
  • Nützlich, wenn man in Markdown-Dokumenten wie GitHub-PRs bestimmte Templates oder Checklisten prüfen möchte
    • Zum Beispiel kann man den Befehl mdq '- [ ]' verwenden, um nicht erledigte Aufgaben zu finden

Grundlegende Verwendung

  • Abschnitt auswählen, der „usage“ enthält: cat example.md | mdq '# usage'
  • Filter können verkettet werden: cat example.md | mdq '# usage | -'
  • Vor dem Einreichen eines Bug-Reports prüfen, ob nach bestehenden Issues gesucht wurde: mdq -q '- [x] I have searched for existing issues'
  • Referenz-Ticket extrahieren: Wenn ein PR ein Ticket erwähnt, können Links aus Markdown als JSON extrahiert und mit jq die URL geholt werden.
    TICKET_URL="$(echo "$PR_TEXT" | mdq --output json '# Ticket | [](^https://tickets.example.com/[A-Z]+-\\d+$)' | jq -r '.items[].link.url')"
  • Große Tabellen eingrenzen: Tabellen können gefiltert werden, um den On-Call-Plan für ein bestimmtes Datum oder eine bestimmte Person zu finden.
    • On-Call-Daten von Alice finden: cat oncall.md | mdq ':-: /On-Call|Alice/:-: *'
    • Zuständige On-Call-Person für die Woche vom 15. Januar 2024 finden: cat oncall.md | mdq ':-: * :-: 2024-01-15'

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2025-02-24
Hacker-News-Kommentare

  • GitHub-PRs sind Markdown-Dokumente, und einige Organisationen verwenden bestimmte Templates mit Checklisten, die von allen Reviewern abgeschlossen werden müssen

    • Um so etwas zu erzwingen, muss man komplexe reguläre Ausdrücke verwenden, die schwer zu schreiben und noch schwerer zu debuggen sind
    • GitHub konzentriert sich auf KI, statt die nötigen Funktionen zu entwickeln
    • Bitbucket bietet eine Funktion, mit der sich ein PR mithilfe einer Checkbox-Liste außerhalb des Beschreibungsfelds blockieren lässt
    • Es gibt einen besseren Weg, dieses Problem zu lösen; siehe dazu das erste Beispiel im README des OP
    • Tolles Projekt, und da ich in letzter Zeit hauptsächlich MDX schreibe, wäre Support für diesen Dialekt schön

  • Einer der Gründe, warum textbasierte Dateiformate wie Markdown populär wurden, ist, dass man sie mit regulären Ausdrücken analysieren und per Versionsverwaltung verwalten konnte

  • Mein Workflow läuft über den Pandoc-JSON-AST und verwendet danach Jq

    • Das funktioniert auch mit anderen Eingabeformaten

  • Danke fürs Teilen, ich werde es mir ansehen

    • Ich wollte etwas Ähnliches

  • Nachdem ich vieles ausprobiert habe, ist das einzige „Notizsystem“, das ich weiterhin benutze, ein Verzeichnis mit Markdown-Dateien, die bei Änderungen automatisch in git committet werden

  • Ich wollte ein paar smarte Funktionen hinzufügen, um Arbeit nachverfolgbar zu machen

    • Zum Beispiel erledigte Aufgaben aufräumen, unerledigte Aufgaben ins Journal des nächsten Tages übernehmen und Aufgaben aus „Projekten“ einsammeln
    • Dafür habe ich angefangen, etwas Rust-Code mit markdown-rs zu schreiben
    • Für das Round-Trippen von Markdown zusammen mit Änderungen wird aktuell nur die JavaScript-Version der Bibliothek unterstützt, die Markdown im GitHub-Stil serialisiert
    • Deshalb habe ich für einen Proof of Concept in Rust den Markdown-AST als JSON gedumpt und in JavaScript serialisiert
    • markdown-rs speichert Positionsinformationen, aber keine Informationen zu Source-Tokens
    • Daher ist kein zuverlässiges Round-Trippen möglich

  • Ich wollte Markdown-Dokumente wie einen Baum behandeln

    • Ich wollte eine Sprache ähnlich wie xpath verwenden, um anhand von Überschriften Abschnitte zu extrahieren
    • Ich werde mir den Code jedenfalls ansehen, danke fürs Posten

  • MarkdownDB bietet ein SQLite-Backend für Markdown-Dateien

    • Ich habe das Gefühl, dass die Struktur von .md-Dateien nicht immer als Ziel der Datenserialisierung respektiert oder überhaupt berücksichtigt wird

  • Danke fürs Teilen; ich habe im Moment keinen unmittelbaren Anwendungsfall dafür, aber es ist gut zu wissen, dass es so etwas gibt

  • Ich wollte einen kleinen Hinweis zu den dokumentierten Shell-Aufrufen geben

    • Zum Beispiel kann cat example.md | mdq '# usage' in eine stdin-Dateiumleitung geändert werden, um den unnötigen cat-Prozess zu vermeiden
    • Ähnlich kann auch echo "$ISSUE_TEXT" | mdq -q '- [x] I have searched for existing issues' den unnötigen echo-Prozess vermeiden

  • Es wäre gut, dem README ein paar realistischere Beispiele hinzuzufügen

    • Das würde Leuten helfen, die nicht sofort intuitiv verstehen, wofür man es verwenden kann

  • Eine interessante Sache, die ich beim Untersuchen bestehender Tools und Bibliotheken gelernt habe, ist, dass viele Tools Markdown erst in HTML serialisieren, bevor sie strukturierte Extraktion oder Manipulation durchführen

    • Markdown ist so entworfen, dass es zu HTML serialisiert wird, daher ist ein Markdown-Dokument bzw. -AST im Wesentlichen meist keine Baumstruktur
    • Stattdessen ist es ein Array von Elementen in der Reihenfolge, in der sie im Dokument erscheinen
    • Nur Listen und Blockzitate unterstützen Verschachtelung
    • Zum Beispiel sind h1 -> Absatz -> h2 -> Absatz nicht verschachtelt, sondern ein Array aus vier geordneten Elementen
    • Wenn man eine Implementierung mit HTML in Cursor oder Copilot testet, könnte man schneller vorankommen

  • Ich glaube, ich habe dieses Tool genau im richtigen Moment entdeckt

    • Es wird für eine bestimmte Aufgabe perfekt passen

  • Danke, Yuval, dass du dieses Tool geteilt hast, und danke für die freizügige Lizenz, sodass ich es bei der Arbeit verwenden kann