Convert a URL to Markdown with metadata frontmatter
URL to Markdown with metadata means every converted page arrives with its title, author and date attached, not just its text. A Markdown body without them is hard to index and harder to cite, which hurts RAG loaders, static site importers, note apps and research archives alike. The Markdown API can prepend the page’s normalized metadata as YAML frontmatter, so each document describes itself.
Markdown without metadata is hard to index and cite
Pipelines that feed LLMs, search indexes or knowledge bases need more than the text: who wrote it, when, what it is about, how long it is. Without those fields a retrieved chunk cannot be attributed, sorted by date or filtered by language, and the answer built on it cannot cite its source.
Scraping those fields separately means a second request and a second parser. Open Graph, Twitter Cards, JSON-LD and plain HTML tags disagree with each other and vary per site, so the metadata code grows a special case for every source. Then the two results have to be joined, and they may not even describe the same version of the page.
Set meta to true on a Markdown request served with embed and Microlink prepends a YAML frontmatter block: title, author, date, publisher, language, description and canonical URL, the image and logo with their dimensions, plus word count and reading time. The Markdown body follows, from the same fetch.
How to get Markdown with YAML frontmatter from a URL
The direct Markdown response carries the frontmatter. In the SDK, the same fields ride along as JSON next to the Markdown rule through the metadata method.
curl 'https://api.microlink.io/?url=https%3A%2F%2Fexample.com%2Fblog%2Fpost&data.markdown.attr=markdown&meta=true&embed=markdown'The response body is text/markdown: a YAML block between two --- lines with keys such as title, author, date, word_count and reading_time, then the converted page. Save it as a .md file and any frontmatter-aware loader can read it.
import createClient from 'microlink.io'
const microlink = createClient({
apiKey: process.env.MICROLINK_API_KEY
})
const { title, author, date, markdown } = await microlink.metadata(
'https://example.com/blog/post',
{ data: { markdown: { attr: 'markdown' } } }
)metadata() returns the normalized fields, and the markdown rule adds the body to the same object. One request, one cache entry, no YAML to parse.
import createClient from 'microlink.io'
const microlink = createClient({
apiKey: process.env.MICROLINK_API_KEY
})
const page = await microlink.metadata('https://example.com/blog/post', {
data: { markdown: { attr: 'markdown' } }
})
const document = [
'---',
`title: ${JSON.stringify(page.title)}`,
`author: ${JSON.stringify(page.author)}`,
`date: ${page.date}`,
`source: ${page.url}`,
'---',
'',
page.markdown
].join('\n')When you want a custom field set, different key names or extra fields such as a collection id, compose the frontmatter yourself from the JSON response.
- meta true detects the normalized fields. With embed=markdown they become the YAML frontmatter. Default true.
- data The Markdown rule: data.markdown.attr=markdown serializes the page as Markdown.
- embed Return the Markdown field as the response body with a text/markdown content type.
- prerender true forces a browser render for client-side pages whose metadata only exists after JavaScript runs. Default auto.
Fields that cannot be detected come back as null in JSON, so consumers should treat every field as optional. The data fields reference documents each normalized field and how it is resolved.
Why YAML frontmatter is the right container for page metadata
Frontmatter is the convention that static site generators, note apps and RAG loaders already understand, so the metadata travels inside the file instead of in a sidecar.
The choosing fields guide shows how to request only the keys you index when you work with the JSON response, and the Metadata API page covers the normalization itself.
Pair it with clean Markdown scoped to the content when navigation and footers would otherwise pad the body.
When not to: if you only need the body for a summarizer, keep meta at false. Skipping metadata detection is the first speedup the performance guide recommends for content-only requests.
FAQ
Which fields appear in the Markdown frontmatter?
How do I convert a URL to Markdown with metadata in one request?
Can I get the Markdown frontmatter fields as JSON instead of YAML?
Does Markdown frontmatter work for PDFs and office documents?
Can I choose which fields go into the Markdown frontmatter?
Solve the next problem with the same API
Clean Markdown, no boilerplate
PDF and office documents to Markdown
LLM context from any URL
Bulk Markdown conversion with caching
Custom fields alongside metadata
Only the fields you need
Ready for self-describing Markdown?
Title, author, date and reading time on top of every converted page. Start on the free tier and feed your pipeline documents that explain themselves.