html-to-markdown-extracting-metadata

Extracting metadata

Use this when the user wants structured metadata out of HTML rather than (or in addition to) the Markdown body — page title, description, language, Open Graph tags, structured data, the heading outline, links, or image references.

Metadata lives in result.metadata and is surfaced on the CLI through --json. On the CLI, metadata extraction is opt-in: pass --extract-metadata alongside --json, otherwise result.metadata comes back empty (document.title is null, headers/links/images/structured_data are []). The library convert() call extracts metadata by default (extract_metadata=True) — that default is a property of the API, not the CLI. There are no per-field extraction flags: --extract-metadata populates all sub-fields below at once.

Get all metadata

html-to-markdown --json --extract-metadata input.html | jq '.metadata'

# Extraction-only (skip the Markdown body)
html-to-markdown --json --extract-metadata --no-content input.html | jq '.metadata'

Metadata sub-fields

{
  "metadata": {
    "document": { "title": "...", "description": "...", "language": "en", "open_graph": {"title": "..."} },
    "headers": [ { "level": 1, "text": "Main Heading" } ],
    "links":   [ { "href": "https://example.com", "link_type": "external" } ],
    "images":  [ { "src": "photo.jpg", "alt": "A photo", "image_type": "external" } ],
    "structured_data": [ /* JSON-LD, Microdata, RDFa blocks */ ]
  }
}

Metadata flag

There is one metadata flag: --extract-metadata. With --json set it populates all sub-fields above (document, headers, links, images, structured_data) under result.metadata — select what you need with jq.

Flag	Effect
--extract-metadata	With --json: populate result.metadata. In plain-text mode (no --json): prepend title + meta tags as a YAML frontmatter block (----delimited) at the top of the Markdown output

# Pull just the document-level metadata and the heading outline
html-to-markdown --json --extract-metadata --no-content input.html \
  | jq '{title: .metadata.document.title, lang: .metadata.document.language, outline: [.metadata.headers[].text]}'