# PDF & DOCX to Markdown + JSON for RAG & LLMs (`benventions/document-to-markdown-json`) Actor

Convert PDF, DOCX, PPTX and XLSX files from URLs into clean Markdown and structured JSON with pages, sections, metadata and RAG-ready chunks.

- **URL**: https://apify.com/benventions/document-to-markdown-json.md
- **Developed by:** [BENVENTIONS](https://apify.com/benventions) (community)
- **Categories:** AI, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Document to Markdown & JSON

Give it links to PDF, Word (DOCX), PowerPoint (PPTX) or Excel (XLSX) files. You get back clean Markdown for each document, plus JSON with the title, page-by-page text, a section outline, file metadata and optional chunks sized for embeddings or RAG.

### What you get per document

| Field | What it is |
| --- | --- |
| `markdown` | The whole document as Markdown. PDF headings are worked out from font size and weight, wrapped lines are joined back into paragraphs, and hyphenated line breaks are healed. Word, PowerPoint and Excel keep their headings, lists and tables. |
| `pages` | One entry per PDF page, slide or sheet, each with its own Markdown. Turn off with `includePages`. |
| `sections` | The document split at each heading: `heading`, `level` and `text`. |
| `chunks` | Only when `chunkSize` is set. Splits on paragraph boundaries where it can, never goes over `chunkSize` characters, overlaps by `chunkOverlap`, and records the heading each chunk sits under. |
| `title`, `metadata` | The document title (from file properties when they look real, otherwise the first heading) and PDF metadata such as author and dates. |
| `pageCount`, `pagesConverted`, `billablePages` | How long the file is, how much was converted, and how many pages you're charged for. |
| `scannedPagesSuspected`, `warnings` | PDF pages with little or no text (likely scans), truncation notices and anything else worth knowing. |

### Input

```json
{
  "documents": [{ "url": "https://example.com/annual-report.pdf" }],
  "chunkSize": 1500,
  "chunkOverlap": 200
}
```

- `maxPagesPerDocument` (default 300): only the first N pages, slides or sheets are converted and charged.
- `maxFileSizeMb` (default 50): bigger files are skipped and not charged.
- `includePages` (default on): adds the per-page array.

Links must be direct downloads. If a link returns a web page or a login screen instead of a file, it's skipped and not charged. The file type is read from the file itself, not the extension.

### Example output

A real run on `sample.docx`, the small test file in this repo's `tests/fixtures` folder (4 Nov 2026). The `sourceUrl` is shown as a placeholder.

```json
{
  "sourceUrl": "https://example.com/sample.docx",
  "fileName": "sample.docx",
  "fileType": "docx",
  "sizeBytes": 36853,
  "title": "Quarterly Report",
  "pageCount": null,
  "pagesConverted": null,
  "billablePages": 1,
  "truncated": false,
  "wordCount": 20,
  "charCount": 175,
  "markdown": "# Quarterly Report\n# Summary\n\nRevenue grew strongly this quarter across all regions.\n\n# Details\n\n* First point.\n* Second point.\n\n| Region | Sales |\n| --- | --- |\n| WA | 120 |\n",
  "sections": [
    {
      "heading": "Quarterly Report",
      "level": 1,
      "text": ""
    },
    {
      "heading": "Summary",
      "level": 1,
      "text": "Revenue grew strongly this quarter across all regions."
    },
    {
      "heading": "Details",
      "level": 1,
      "text": "* First point.\n* Second point.\n\n| Region | Sales |\n| --- | --- |\n| WA | 120 |"
    }
  ],
  "metadata": {},
  "scannedPagesSuspected": [],
  "warnings": [],
  "convertedAt": "2026-11-04T05:29:12.806845+00:00"
}
```

### What it doesn't do

- No OCR. Scanned PDFs come back flagged in `scannedPagesSuspected` with little or no text.
- PDF tables come out as text, not Markdown tables. Tables in Word, PowerPoint and Excel are kept as tables.
- Two-column PDF layouts can have their columns run together on some pages.
- Old `.doc`, `.ppt` and `.xls` files aren't supported. Save them in the newer format first.
- Password-protected files are skipped.
- Very large outputs that won't fit in one dataset item are saved to the run's key-value store, and the item tells you the key.

### Pricing

Pay per event: **US$0.003 per page for the first 50 pages of each document, then US$0.001 per page after that.** A 10-page PDF costs US$0.03, and a 300-page PDF costs US$0.40. A PDF page, a slide or a spreadsheet sheet counts as one page. Word files don't have fixed pages, so they're counted as one page per 500 words, rounded up. Files that fail to download or convert aren't charged. If a document needs more page charges than your maximum spend allows, the run stops before converting it.

### Limits and good use

- This Actor only reads files you link to. It doesn't log in, get past paywalls or captchas, or work around blocks.
- It converts the text of the documents you give it and doesn't look up or add information about anyone. If your files contain names or contact details, they'll appear in the output as they appear in the file.
- It downloads one file at a time and follows each site's robots.txt rules.
- Only run it on files you own or are allowed to process. You're responsible for using the results in line with the laws that apply to you and the terms of any site you download from.
- You're only charged for results the Actor actually delivers. Failed or empty conversions aren't billed.
- This Actor isn't affiliated with, endorsed by or sponsored by any site, search engine or AI company it mentions.
- Your files are processed only to produce your output and aren't kept by us after the run. Apify stores run data under your own account's retention settings.
- Don't upload documents you don't have the right to process. If your files contain personal or sensitive information, you're responsible for handling it lawfully.

# Actor input Schema

## `documents` (type: `array`):

Direct download links to PDF, DOCX, PPTX or XLSX files. Files must be publicly downloadable.

## `maxPagesPerDocument` (type: `integer`):

Only the first N pages, slides or sheets are converted and charged.

## `maxFileSizeMb` (type: `integer`):

Larger files are skipped and not charged.

## `chunkSize` (type: `integer`):

Split the Markdown into chunks for RAG or embeddings. 0 turns chunking off.

## `chunkOverlap` (type: `integer`):

Characters repeated between neighbouring chunks.

## `includePages` (type: `boolean`):

Add a pages array with Markdown for each PDF page, slide or sheet.

## Actor input object example

```json
{
  "documents": [
    {
      "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
    }
  ],
  "maxPagesPerDocument": 300,
  "maxFileSizeMb": 50,
  "chunkSize": 0,
  "chunkOverlap": 200,
  "includePages": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "documents": [
        {
            "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("benventions/document-to-markdown-json").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "documents": [{ "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" }] }

# Run the Actor and wait for it to finish
run = client.actor("benventions/document-to-markdown-json").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "documents": [
    {
      "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
    }
  ]
}' |
apify call benventions/document-to-markdown-json --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,benventions/document-to-markdown-json"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/YbU35RPbS1HCKIE35/builds/qV2UmxNfCfMLriGBA/openapi.json