treemd tql查询语言进阶技巧:层级运算符、管道过滤与6种输出格式完全指南

原创2026-10-31 22:34:291,952 阅读

treemd tql查询语言进阶技巧:层级运算符、管道过滤与6种输出格式完全指南

treemd 是一款终端里的 Markdown 导航工具,内置了类似 jq 的 tql(treemd query language,查询语言),让你用一行命令就能提取标题、代码块、链接等结构化内容。本文面向已会用基础选择器的用户,深入讲解 层级运算符(> 与 >>)、管道过滤(select()) 以及 6 种输出格式 的进阶技巧,帮你把 treemd 变成高效的 Markdown 分析与脚本处理利器 🚀。

treemd tql查询语言在终端中的双栏导航界面

1 分钟认识 tql:像 jq 一样查询 Markdown

tql 的语法借鉴了 jq:点号选择元素、| 管道串联操作、[...] 做索引与切片。基本用法:

treemd -q '.h2' doc.md            # 所有 h2 标题
treemd -q '.h2 | text' doc.md     # 去掉 ##,只要纯文本
treemd -q '.code[rust]' doc.md    # 所有 Rust 代码块

不确定语法时,随时运行 treemd --query-help 查看内置完整参考,等价于仓库中的 query-language.md。

层级运算符:用 > 和 >> 精确锁定文档结构

这是 tql 最有价值的特性之一——直接描述元素间的父子层级关系,语法类似 CSS 组合器:

treemd -q '.h1 > .h2' doc.md             # h1 的“直接子级” h2
treemd -q '.h1 >> .code' doc.md          # h1 下方任意深度的代码块
treemd -q '.h1[Features] > .h2' doc.md   # 只取 Features 章节的直接子标题
运算符 含义 典型场景
> 直接子元素 只统计某章节的一级小节
>> 任意深度后代 收集某章节下所有代码/链接

实战:找出 “Examples” 章节下超过 20 行的代码块:

treemd -q '.h1[Examples] >> .code | select(.text | lines > 20)' doc.md

💡 提示:parent、children 等导航函数目前尚未实现,直接用 > 和 >> 即可完成绝大多数导航需求(详见设计说明 QUERY_LANGUAGE.md)。

管道过滤:select() + 组合条件,把结果收窄到最小

管道 | 把上一步的输出传给下一步,配合 select() 可以层层过滤:

# 文本匹配
treemd -q '.h | select(contains("API"))' doc.md      # 包含 API 的标题
treemd -q '.h | select(startswith("Chapter"))' doc.md # 前缀匹配

# 属性比较
treemd -q '.code | select(.lang == "rust")' doc.md    # 按语言筛选
treemd -q '.link | select(.type == "external")' doc.md # 只要外部链接

# 组合条件(and / or / not)
treemd -q '.h | select(.level >= 2 and contains("API"))' doc.md
treemd -q '.code | select(.lang == "rust" or .lang == "python")' doc.md

集合函数让过滤后的结果立刻可用:

treemd -q '.h | count' doc.md          # 标题总数
treemd -q '.h | text | upper' doc.md   # 转大写
treemd -q '.code | lang | unique' doc.md # 去重:本文用了哪些语言
treemd -q '.link | group_by(.type)' doc.md # 按类型分组统计链接

完整的函数清单(集合、字符串、内容、聚合四大类)可在 QUERY_LANGUAGE.md 的 “Built-in Functions” 一节查到。

6 种输出格式:--query-output 参数详解

查询结果默认是纯文本,加上 --query-output 可切换 6 种格式:plain、json、json-pretty、jsonl、md、tree(实现见 output.rs)。

treemd -q '.h2' doc.md                                   # plain(默认)
treemd -q '.h2' --query-output json doc.md                # 紧凑 JSON
treemd -q '.h2' --query-output json-pretty doc.md         # 缩进美化的 JSON
treemd -q '.h2 | text' --query-output jsonl doc.md        # 每行一个 JSON 对象
treemd -q '.h1[Install] | md' doc.md                      # 原始 Markdown 片段
treemd -q '.h' --query-output tree doc.md                 # 树形结构

各格式适用场景:

格式 适用场景
plain 肉眼查看,默认
json 传给 jq 等工具做二次处理
json-pretty 调试、贴文档
jsonl 日志流、逐行处理
md 提取整段 Markdown 内容再加工
tree 快速浏览标题层级

⚠️ 常见坑:-q 模式下 -o 参数会被静默忽略(-o 只作用于 --list/--tree),一定要用 --query-output,否则你会得到纯文本并以为查询失败了。

管道组合示例——统计文档代码块数量并交给 jq 读取:

treemd -q 'stats' --query-output json doc.md | jq '.code_blocks'

三个实用进阶场景

1️⃣ 自动生成目录(按标题层级缩进):

treemd -q '.h[] | "  " * (.level - 1) + "- " + .text' doc.md

2️⃣ 提取某个章节的完整内容:

treemd -q '.h1[Installation] | content' doc.md   # 纯文本
treemd -q '.h1[Installation] | md' doc.md        # 保留 Markdown 语法

3️⃣ 生成站点地图 JSON(一次输出结构化数据):

treemd -q '[.h[] | {level: .level, text: .text, slug: (.text | slugify)}]' \
  --query-output json-pretty doc.md

此外 tql 支持 stdin,cat doc.md | treemd -q '.h2' 一样有效,方便嵌入 Shell 工作流。

写在最后

掌握 >/>> 层级运算符、select() 管道过滤 和 --query-output 六种输出格式,treemd 的 tql 查询语言就足以覆盖绝大多数 Markdown 结构化分析需求:从生成目录、统计代码块到批量抽取章节,全部一条命令搞定 ✅

更多细节参考:

登录后查看全文
treemd