mdq - Markdownのためのjq

 (github.com/yshavit)
7 ポイント 投稿者 GN⁺ 2025-02-24 | 1件のコメント | WhatsAppで共有
  • mdqは、Markdownドキュメント内の特定部分を簡単に見つけられるようにするツール
  • GitHub PRのようなMarkdownドキュメントで、特定のテンプレートやチェックリストを確認するときに便利
    • たとえば、未完了の作業を見つけるために mdq '- [ ]' コマンドを使用可能

基本的な使い方

  • "usage" を含むセクションを選択: cat example.md | mdq '# usage'
  • フィルターをチェーンして使用可能: cat example.md | mdq '# usage | -'
  • バグレポート提出前に既存のissue検索を確認: mdq -q '- [x] I have searched for existing issues'
  • 参照チケットを抽出: PRがチケットに言及しているとき、MarkdownからリンクをJSONとして抽出し、jqでURLを取得可能。
    TICKET_URL="$(echo "$PR_TEXT" | mdq --output json '# Ticket | [](^https://tickets.example.com/[A-Z]+-\d+$)' | jq -r '.items[].link.url')"
  • 大きなテーブルを絞り込み: 特定の日付や担当者のon-callスケジュールを見つけるために、テーブルをフィルタリング可能。
    • Aliceのon-call日を見つける: cat oncall.md | mdq ':-: /On-Call|Alice/:-: *'
    • 2024年1月15日の週のon-call担当者を見つける: cat oncall.md | mdq ':-: * :-: 2024-01-15'

関連記事

1件のコメント

 
GN⁺ 2025-02-24
Hacker Newsのコメント

  • GitHubのPRはMarkdownドキュメントであり、一部の組織では、すべてのレビュアーが完了しなければならないチェックリストを含む特定のテンプレートを使用している

    • このような機能を強制するには複雑な正規表現を使う必要があり、これは書くのが難しく、デバッグはさらに難しい
    • GitHubは必要な機能を開発せず、AIに注力している
    • Bitbucketには、説明ボックスの外側にあるチェックボックス一覧を使ってPRをブロックできる機能がある
    • この問題を解決するもっと良い方法があり、OPのREADMEにある最初の例を参照できる
    • すばらしいプロジェクトで、最近は主にMDXを書いているので、その方言への対応があるとうれしい

  • Markdownのようなテキストベースのファイル形式が人気を集めた理由の1つは、正規表現で解析でき、バージョン管理で扱えたからである

  • 自分のワークフローは、Pandoc JSON ASTを経由してからJqを使う形で進めている

    • これは他の入力形式にも機能する

  • 共有してくれてありがとう、見てみるつもり

    • 似たようなものを欲しいと思っていた

  • いろいろ試した結果、今も使い続けている唯一の「ノートシステム」は、変更時に自動でgitへコミットされるMarkdownファイルのディレクトリである

  • 少しスマートな機能を追加して、作業を追跡できるようにしたかった

    • たとえば、完了したタスクを整理したり、未完了のタスクを翌日のジャーナルへ持ち越したり、「プロジェクト」からタスクを集約したりといったこと
    • そのためにmarkdown-rsを使ってRustコードを書き始めた
    • 変更込みでMarkdownをラウンドトリップするには、現時点ではGitHubスタイルのMarkdownをシリアライズするライブラリのJavaScript版しか対応していない
    • そこで、RustでMarkdown ASTをJSONにダンプし、JavaScriptでシリアライズして概念実証を行った
    • markdown-rsは位置情報を保存するが、ソーストークン情報は保存しない
    • そのため、信頼できるラウンドトリップは不可能である

  • Markdownドキュメントをツリーとして扱いたかった

    • 見出しに基づいてセクションを抽出するために、xpathのような言語を使いたかった
    • ともかくコードを確認してみる、投稿してくれてありがとう

  • MarkdownDBはMarkdownファイル向けのSQLiteバックエンドを提供している

    • .mdファイルの構造は、常にデータシリアライズの対象として尊重または考慮されているわけではないと感じる

  • 共有してくれてありがとう、今のところ自分にはすぐのユースケースはないが、こういうものがあると知れてよかった

  • ドキュメント化されたシェル呼び出しについて、小さな指摘をしたい

    • たとえば、cat example.md | mdq '# usage'は、不要なcatプロセスを起動しないようにstdinのファイルリダイレクトへ変更できる
    • 同様に、echo "$ISSUE_TEXT" | mdq -q '- [x] I have searched for existing issues'も、不要なechoプロセスを避けられる

  • READMEにもっと現実的な例を追加するとよいと思う

    • 直感的に用途が分からない人の助けになるはず

  • 既存のツールやライブラリを調べる中で学んだ興味深い点の1つは、多くのツールが、構造化された抽出や操作を行う前にMarkdownをHTMLへシリアライズしていること

    • MarkdownはHTMLへシリアライズされるよう設計されているため、Markdownドキュメント/ASTは主としてツリー構造ではない
    • その代わり、ドキュメントに現れる順序どおりの要素配列である
    • ネストをサポートしているのは、リストとブロック引用だけである
    • たとえば、h1 -> 段落 -> h2 -> 段落はネストされず、順序付きの4要素の配列である
    • CursorやCopilotにHTMLを使った実装を試させれば、より速く開発できるかもしれない

  • このツールを、まさに必要としていた瞬間に見つけた気がする

    • 特定の作業に完璧に合いそう

  • Yuvalにこのツールを共有してくれてありがとう、また寛容なライセンスを採用してくれたおかげで職場で使えることにも感謝している