用途：当需要从 HTML 中取出结构化元数据（而非仅正文 Markdown）时使用，可获取页面标题、描述、语言、Open Graph 标签、结构化数据、标题大纲、链接和图片引用。
主要能力：元数据位于 result.metadata，CLI 中通过 --json 呈现。CLI 的元数据提取需显式开启：同时传 --extract-metadata 与 --json，否则 result.metadata 为空（document.title 为 null，headers/links/images/structured_data 为 []）。库函数 convert() 默认提取元数据（extract_metadata=True），这是 API 默认值而非 CLI 行为。没有按字段的提取开关，--extract-metadata 一次性填充全部子字段。
子字段：metadata 下含 document（title、description、language、open_graph）、headers（level、text）、links（href、link_type）、images（src、alt、image_type）、structured_data（JSON-LD、Microdata、RDFa 块）。
使用方式：全部元数据 html-to-markdown --json --extract-metadata input.html | jq '.metadata'；仅提取不生成正文加 --no-content。用 jq 可筛选所需字段，如 metadata.document.title、language、headers 文本、link_type 为 external 的链接、open_graph、structured_data。纯文本模式下 --extract-metadata 会把 title 与 meta 标签作为 YAML frontmatter 前置到 Markdown 顶部。
程序化访问：Python 中 from html_to_markdown import convert，调用 convert(html) 后读 result.metadata 的 document.title、language、headers[0].text、links[0].link_type、images[0].alt。元数据在 Python、Rust、Go、Ruby、Elixir 的单个 convert() 调用中可用；TypeScript 从返回结果对象读取；Rust 需 metadata feature（默认开启）。
限制：CLI 默认不提取元数据，需显式传参；字段细节见 references/cli-reference.md 与 references/configuration.md。