mdq - jq para Markdown

 (github.com/yshavit)
7 pontos por GN⁺ 2025-02-24 | 1 comentários | Compartilhar no WhatsApp
  • mdq é uma ferramenta que ajuda a encontrar facilmente partes específicas em documentos Markdown
  • Útil para verificar templates ou checklists específicos em documentos Markdown como PRs do GitHub
    • Por exemplo, é possível usar o comando mdq '- [ ]' para encontrar tarefas não concluídas

Uso básico

  • Selecionar a seção que contém "usage": cat example.md | mdq '# usage'
  • É possível encadear filtros: cat example.md | mdq '# usage | -'
  • Confirmar a busca por issues existentes antes de enviar um bug report: mdq -q '- [x] I have searched for existing issues'
  • Extrair ticket de referência: quando um PR menciona um ticket, é possível extrair links do Markdown como JSON e obter a URL com jq.
    TICKET_URL="$(echo "$PR_TEXT" | mdq --output json '# Ticket | [](^https://tickets.example.com/[A-Z]+-\d+$)' | jq -r '.items[].link.url')"
  • Reduzir tabelas grandes: é possível filtrar a tabela para encontrar a escala de plantão de uma data específica ou de uma pessoa.
    • Encontrar as datas de plantão da Alice: cat oncall.md | mdq ':-: /On-Call|Alice/:-: *'
    • Encontrar a pessoa de plantão na semana de 2024-01-15: cat oncall.md | mdq ':-: * :-: 2024-01-15'

Leituras relacionadas

1 comentários

 
GN⁺ 2025-02-24
Comentários no Hacker News

  • Um PR no GitHub é um documento Markdown, e algumas organizações usam templates específicos que incluem checklists que todos os revisores precisam concluir

    • Para impor esse tipo de recurso, é preciso usar expressões regulares complexas, que são difíceis de escrever e ainda mais difíceis de depurar
    • O GitHub está focado em IA em vez de desenvolver os recursos necessários
    • O Bitbucket oferece um recurso que permite bloquear PRs usando uma lista de caixas de seleção fora da caixa de descrição
    • Há uma maneira melhor de resolver esse problema, e você pode ver o primeiro exemplo no README do OP
    • Projeto muito legal, e como hoje em dia escrevo principalmente em MDX, seria bom ver suporte para esse dialeto

  • Um dos motivos pelos quais formatos de arquivo baseados em texto como Markdown ficaram populares foi porque podiam ser analisados com expressões regulares e gerenciados com controle de versão

  • Meu fluxo de trabalho passa pelo JSON AST do Pandoc e depois usa Jq

    • Isso também funciona para outros formatos de entrada

  • Obrigado por compartilhar, vou dar uma olhada

    • Eu queria algo parecido

  • Depois de tentar várias coisas, o único "sistema de notas" que continuo usando é um diretório de arquivos Markdown que faz commit automático no git quando há mudanças

  • Eu queria adicionar alguns recursos inteligentes para poder acompanhar tarefas

    • Por exemplo, limpar tarefas concluídas, levar tarefas não concluídas para o diário do dia seguinte e coletar tarefas de "projetos"
    • Para isso, comecei a escrever um pouco de código Rust usando markdown-rs
    • Para fazer round-trip de Markdown junto com as alterações, no momento só há suporte para a versão JavaScript da biblioteca que serializa Markdown no estilo do GitHub
    • Então fiz uma prova de conceito despejando o AST de Markdown em JSON no Rust e serializando em JavaScript
    • O markdown-rs armazena informações de posição, mas não armazena informações dos tokens de origem
    • Portanto, um round-trip confiável é impossível

  • Eu queria tratar documentos Markdown como uma árvore

    • Queria usar uma linguagem tipo xpath para extrair seções com base nos headings
    • De qualquer forma, vou conferir o código, obrigado por publicar

  • O MarkdownDB oferece um backend SQLite para arquivos Markdown

    • Tenho a sensação de que a estrutura dos arquivos .md nem sempre é respeitada ou considerada como alvo de serialização de dados

  • Obrigado por compartilhar, no momento não tenho um caso de uso imediato para isso, mas é bom saber que algo assim existe

  • Queria mencionar uma pequena observação sobre as chamadas de shell documentadas

    • Por exemplo, cat example.md | mdq '# usage' pode ser trocado por redirecionamento de arquivo via stdin para evitar invocar um processo cat desnecessário
    • De forma semelhante, echo "$ISSUE_TEXT" | mdq -q '- [x] I have searched for existing issues' também pode evitar um processo echo desnecessário

  • Acho que seria bom adicionar exemplos mais realistas no README

    • Isso ajudaria quem não entende intuitivamente para que serve

  • Uma coisa interessante que aprendi ao pesquisar ferramentas e bibliotecas existentes é que muitas delas serializam Markdown para HTML antes de executar extração/manipulação estruturada

    • Como o Markdown foi projetado para ser serializado em HTML, o documento/AST de Markdown em geral não é principalmente uma estrutura em árvore
    • Em vez disso, é um array de elementos na ordem em que aparecem no documento
    • Apenas listas e blockquotes suportam aninhamento
    • Por exemplo, h1 -> parágrafo -> h2 -> parágrafo não é aninhado, e sim um array de quatro elementos ordenados
    • Se você testar uma implementação usando HTML no Cursor ou no Copilot, talvez consiga desenvolver mais rápido

  • Acho que encontrei esta ferramenta exatamente no momento em que precisava dela

    • Ela deve servir perfeitamente para uma tarefa específica

  • Obrigado por compartilhar esta ferramenta com Yuval e por usar uma licença permissiva, o que permite usá-la no trabalho