mdq - jq dành cho Markdown

 (github.com/yshavit)
7 điểm bởi GN⁺ 2025-02-24 | 1 bình luận | Chia sẻ qua WhatsApp
  • mdq là công cụ giúp dễ dàng tìm các phần cụ thể trong tài liệu Markdown
  • Hữu ích khi kiểm tra các mẫu hoặc checklist cụ thể trong tài liệu Markdown như GitHub PR
    • Ví dụ, có thể dùng lệnh mdq '- [ ]' để tìm các công việc chưa hoàn thành

Cách sử dụng cơ bản

  • Chọn section chứa "usage": cat example.md | mdq '# usage'
  • Có thể nối chuỗi các bộ lọc để sử dụng: cat example.md | mdq '# usage | -'
  • Xác nhận đã tìm kiếm các issue hiện có trước khi gửi báo cáo lỗi: mdq -q '- [x] I have searched for existing issues'
  • Trích xuất ticket tham chiếu: khi PR nhắc tới ticket, có thể trích xuất link từ Markdown sang JSON rồi dùng jq để lấy URL.
    TICKET_URL="$(echo "$PR_TEXT" | mdq --output json '# Ticket | [](^https://tickets.example.com/[A-Z]+-\d+$)' | jq -r '.items[].link.url')"
  • Thu gọn bảng lớn: có thể lọc bảng để tìm lịch trực on-call của một ngày cụ thể hoặc một người cụ thể.
    • Tìm ngày trực on-call của Alice: cat oncall.md | mdq ':-: /On-Call|Alice/:-: *'
    • Tìm người trực on-call trong tuần của ngày 2024-01-15: cat oncall.md | mdq ':-: * :-: 2024-01-15'

Bài viết liên quan

1 bình luận

 
GN⁺ 2025-02-24
Ý kiến Hacker News

  • GitHub PR là tài liệu Markdown, và một số tổ chức dùng các mẫu cụ thể có chứa checklist mà mọi reviewer đều phải hoàn thành

    • Để ép buộc tính năng này phải dùng các biểu thức chính quy phức tạp, vốn khó viết và còn khó debug hơn
    • GitHub đang tập trung vào AI thay vì phát triển tính năng cần thiết
    • Bitbucket cung cấp tính năng chặn PR bằng danh sách checkbox nằm ngoài ô mô tả
    • Có cách tốt hơn để giải quyết vấn đề này, có thể xem ví dụ đầu tiên trong README của OP
    • Dự án rất hay, và vì dạo này tôi chủ yếu viết MDX nên sẽ rất tuyệt nếu thấy hỗ trợ cho phương ngữ đó

  • Một trong những lý do các định dạng tệp dựa trên văn bản như Markdown trở nên phổ biến là vì chúng có thể được phân tích bằng biểu thức chính quy và quản lý thông qua kiểm soát phiên bản

  • Quy trình làm việc của tôi là đi qua Pandoc JSON AST rồi dùng Jq

    • Cách này cũng hoạt động với các định dạng đầu vào khác

  • Cảm ơn vì đã chia sẻ, tôi sẽ thử xem

    • Tôi cũng từng muốn một thứ tương tự

  • Sau khi thử nhiều thứ khác nhau, "hệ thống ghi chú" duy nhất mà tôi vẫn tiếp tục dùng là một thư mục các tệp Markdown được tự động commit vào git khi có thay đổi

  • Tôi muốn thêm một chút tính năng thông minh để có thể theo dõi công việc

    • Ví dụ như dọn dẹp các việc đã hoàn thành, chuyển các việc chưa xong sang nhật ký của ngày hôm sau, và thu thập công việc từ các "project"
    • Để làm việc đó, tôi đã bắt đầu viết một ít mã Rust bằng markdown-rs
    • Để round-trip Markdown cùng với các thay đổi, hiện tại chỉ có bản JavaScript của thư viện hỗ trợ serialize Markdown theo kiểu GitHub
    • Vì vậy tôi đã làm một bản proof of concept bằng cách dump Markdown AST thành JSON trong Rust rồi serialize bằng JavaScript
    • markdown-rs lưu thông tin vị trí nhưng không lưu thông tin token nguồn
    • Vì thế không thể round-trip một cách đáng tin cậy

  • Tôi muốn coi tài liệu Markdown như một cây

    • Tôi muốn dùng một ngôn ngữ kiểu như xpath để trích xuất các section dựa trên heading
    • Dù sao tôi cũng sẽ xem qua mã nguồn, cảm ơn vì đã đăng nó

  • MarkdownDB cung cấp backend SQLite cho các tệp Markdown

    • Tôi có cảm giác cấu trúc của tệp .md không phải lúc nào cũng được tôn trọng hoặc được xem là đối tượng để tuần tự hóa dữ liệu

  • Cảm ơn vì đã chia sẻ, hiện tại tôi chưa có trường hợp sử dụng ngay nhưng thật tốt khi biết có thứ như thế này tồn tại

  • Tôi muốn nêu một góp ý nhỏ về các lệnh shell được ghi lại trong tài liệu

    • Ví dụ, cat example.md | mdq '# usage' có thể đổi sang chuyển hướng tệp stdin để tránh gọi tiến trình cat không cần thiết
    • Tương tự, echo "$ISSUE_TEXT" | mdq -q '- [x] I have searched for existing issues' cũng có thể tránh được tiến trình echo không cần thiết

  • Có lẽ nên thêm các ví dụ thực tế hơn vào README

    • Điều đó sẽ giúp những người không trực giác nhận ra mục đích sử dụng của nó

  • Một điều thú vị tôi học được khi nghiên cứu các công cụ và thư viện hiện có là nhiều công cụ serialize Markdown sang HTML trước khi thực hiện việc trích xuất/thao tác có cấu trúc

    • Vì Markdown được thiết kế để serialize thành HTML, nên tài liệu/AST Markdown về cơ bản không phải là cấu trúc cây
    • Thay vào đó, nó là một mảng các phần tử theo đúng thứ tự xuất hiện trong tài liệu
    • Chỉ có danh sách và block quote là hỗ trợ lồng nhau
    • Ví dụ, h1 -> đoạn văn -> h2 -> đoạn văn không lồng nhau mà là một mảng gồm bốn phần tử có thứ tự
    • Nếu thử cho Cursor hoặc Copilot kiểm tra một triển khai dùng HTML, có lẽ bạn sẽ phát triển nhanh hơn

  • Có vẻ tôi đã tìm thấy công cụ này đúng vào lúc cần nó nhất

    • Nó sẽ cực kỳ phù hợp cho một tác vụ cụ thể

  • Cảm ơn Yuval đã chia sẻ công cụ này, và cảm ơn vì dùng giấy phép permissive để tôi có thể dùng nó ở chỗ làm