Markdown API · Use case

Convert PDF and office document URLs to Markdown

Convert documents to Markdown with the request you already use for HTML: point it at a PDF, DOCX, XLSX or PPTX URL and readable Markdown comes back. Knowledge lives in annual reports, contracts, price sheets and slide decks as much as in web pages. One conversion path lets a RAG pipeline, a support bot or an internal search index ingest all of them.

Start with the Markdown API

The problem

PDF and DOCX files need their own parser, until they do not

Each format brings a library, a set of edge cases and a different output shape. A pipeline that handles HTML, PDF and DOCX ends up with three code paths that produce three flavors of text, and the chunker downstream has to cope with all of them.

Local parsers also mean binaries to install, patch and scale. One library flattens tables, another loses heading levels, a spreadsheet reader hands you arrays instead of text. Every new format a customer uploads becomes another integration to maintain.

Microlink converts a PDF with a text layer, or a docx, xlsx, pptx, odt, rtf or epub file, to an HTML document at fetch time and then serializes it exactly like a web page. The request is identical and only the url changes, which is the same idea behind the file conversion API.

Open the live Markdown of a DOCX file

How it works

How to convert a PDF or DOCX URL to Markdown

Nothing in the request identifies the format. Point it at a direct file URL and the conversion adapts, as the URL to Markdown guide describes for every supported source.

1 · Convert a document with the SDK

import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const markdown = await microlink.markdown(
  'https://cdn.microlink.io/file-examples/sample.docx'
)

The same method converts .pdf, .docx, .xlsx, .pptx, .odt, .rtf and .epub URLs and resolves to a Markdown string with the headings, lists and tables of the document.

2 · Plain text when structure does not matter

import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const text = await microlink.text(
  'https://example.com/reports/annual-report.pdf'
)

The text method strips the markup and collapses whitespace, the smallest readable body for summarizers and classifiers that ignore headings and tables.

3 · The same request as a URL

curl 'https://api.microlink.io/?url=https%3A%2F%2Fcdn.microlink.io%2Ffile-examples%2Fsample.docx&data.markdown.attr=markdown&meta=false&embed=markdown'

embed=markdown returns the Markdown directly with a text/markdown content type. Without it, the converted document arrives in the data.markdown field of the JSON response.

Parameters used

data data.markdown.attr=markdown serializes the fetched document as Markdown.
embed Return the Markdown field as the response body instead of JSON.
meta false skips metadata detection, useful for file URLs that expose little of it. Default true.
headers Forward authorization when the document sits behind a login. Pro plans.
ttl Documents rarely change, so cache the conversion for up to 31 days. Pro plans.

Image-only PDF scans, the legacy doc, xls and ppt formats and the ods and odp formats are not converted. The request still succeeds, but the field holds the raw response instead of Markdown, so validate the value before you index it.

Why it works

Why one Markdown conversion path for pages and documents

Ingestion pipelines are simpler when every source produces the same shape, whether it started as HTML, a Word report or a spreadsheet.

01 · Uniform output

Web page or document, the Markdown looks the same.

Headings become headings, tables become tables, lists become lists. A chunker or an embedder written for web content works unchanged on a Word report or a slide deck, and your prompts never branch on file type.

Add metadata frontmatter with meta: true when the document exposes a title and an author you want to keep.

02 · No local parsers

Conversion happens at fetch time on Microlink’s side.

There is nothing to install and no binary dependency to patch. The document is fetched, converted to an HTML DOM and serialized inside the same request that handles HTML pages.

Large documents take longer to convert. The request timeout is 30 seconds on the free endpoint and 60 seconds on Pro, and a cached conversion skips the work entirely. For a folder of files, see bulk Markdown conversion.

03 · Honest limits

Text layers convert; scans do not.

A PDF made of scanned images has no text to extract, and the legacy binary office formats are not supported. The request still succeeds, so check the field before you index it.

When not to: for scanned documents, run a dedicated OCR step first and feed the resulting text or searchable PDF back in. For the reverse direction, saving web articles as PDF is a PDF API job.

FAQ

Which document formats can I convert to Markdown?

PDF files with a text layer and the office formats docx, xlsx, pptx, odt, rtf and epub, all from a direct file URL. Any HTML page works as before, so the same pipeline handles pages and documents.

How do I convert a PDF URL to Markdown with an API?

Send the PDF URL as the url parameter with data.markdown.attr=markdown, or call microlink.markdown(url) in the SDK. Microlink fetches the file, converts it to an HTML document and serializes it as Markdown. Add embed=markdown to receive the Markdown as the response body.

What happens when I convert a scanned PDF to Markdown?

Image-only scans have no text layer, so the field is left as the raw response instead of Markdown. The request still returns success, which means you should check the value before indexing it and route scans to an OCR step.

Yes, on Pro plans. Forward the session cookie or token with x-api-header-* request headers and the file is fetched as that user, then converted. The private pages guide explains how to keep credentials out of the query string.

Do XLSX spreadsheets keep their tables in Markdown?

Yes. Tables are preserved, so a sheet arrives as Markdown tables. Very wide sheets produce wide tables, so use the text method instead when you only need the cell values.

Related use cases

Solve the next problem with the same API

Markdown with metadata frontmatter

Get each page as Markdown with a YAML frontmatter block: title, author, date, word count and reading time.

Add metadata frontmatter

Bulk Markdown conversion with caching

Convert thousands of URLs in parallel, cached per URL and refreshed in the background for cheap re-indexing.

Convert URLs in bulk

Clean Markdown, no boilerplate

Convert only the article body: one selector keeps navigation, ads and widgets out of the Markdown.

Get clean Markdown

LLM context from any URL

Compose Markdown, links, emails, metadata and tech stack from one URL into a context object for your agent.

Build LLM context

YouTube transcripts as Markdown

Get the caption transcript of any watch, share or shorts URL as Markdown, with the video title, author and date.

Get YouTube transcripts

Archive web articles as PDF

Keep readable, searchable PDFs of articles and docs, printed with their print styles and trimmed to the pages you need.

Archive articles as PDF

Ready to convert documents to Markdown?

PDFs, Word files, spreadsheets and decks through the same request as web pages. Start on the free tier and ingest your first document today.

Convert a document