Skip to content

Commit 9619051

Browse files
NaapperasNaapperas
committed
Added documentation about conversion options in ToMarkdown
1 parent 513a16a commit 9619051

File tree

8 files changed

+379
-43
lines changed

8 files changed

+379
-43
lines changed

‎src/content/changelog/workers-ai/2025-11-14-new-markdown-conversion-options.mdx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: 'Workers AI Markdown Conversion: new conversion options & embedded content conversion'
3+
description: You can now control parts of the markdown conversion process, allowing you to specify if embedded content should be converted as well
4+
date: 2025-11-14
5+
---
6+
7+
Users can now control more aspects of the conversion process when using the Workers AI [Markdown Conversion](/workers-ai/features/markdown-conversion/) service.
8+
9+
By passing a `conversionOptions` object in your request, you can control how conversion is handled for different types of files.
10+
11+
You can use the [`env.AI`](/workers-ai/features/markdown-conversion/usage/binding/) binding:
12+
13+
```typescript
14+
// env.AI.toMarkdown().transform(..., { ... }) works the same
15+
await env.AI.toMarkdown(..., {
16+
conversionOptions: { ... }
17+
});
18+
```
19+
20+
Or call the REST API:
21+
22+
```bash
23+
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown \
24+
-H 'Authorization: Bearer {API_TOKEN}' \
25+
-F 'files=@index.html' \
26+
-F 'conversionOptions={ ... }'
27+
```
28+
29+
to control how conversion happens.
30+
31+
This addition also enables users to convert _embedded content_, such as *data URL* images in HTML files. Given the following HTML markup (where the image is of a cat playing with a ball, for example):
32+
33+
```html
34+
...
35+
<img src="data:image/png;base64,..." alt="My embedded image"/>
36+
...
37+
```
38+
39+
the converted Markdown output would look something like this:
40+
41+
```markdown
42+
...
43+
The image depicts a cat playing with a ball
44+
...
45+
```
46+
47+
If we fail to convert your image, we will fall back to the provided `alt` description, if there is one.
48+
49+
Learn more about the new conversion options and embedded content conversion in the [Markdown Conversion documentation](/workers-ai/features/markdown-conversion/).

‎src/content/docs/workers-ai/features/markdown-conversion/conversion-options.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: Conversion Options
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 4
6+
---
7+
8+
Usually, only a file's **text** content will be converted. For some formats, this might be just the text, while for others some semantic information (like headings and lists) can be retrieved and output as part of the final conversion.
9+
10+
To further extend the capabilities of the conversion process, several options can be passed to the service to control how to convert files.
11+
12+
## Embedded content
13+
14+
With the addition of conversion options, you can now tell the conversion process whether you want to convert embedded content or not. This means that more of your files are converted into Markdown, making these conversions closer to the original content. This can improve results in applications that depend on Markdown content, like [AI Search](/ai-search/concepts/how-ai-search-works/#how-indexing-works/) for example.
15+
16+
## Available options
17+
18+
### Images
19+
20+
```typescript
21+
{
22+
image?: {
23+
descriptionLanguage?: 'en' | 'it' | 'de' | 'es' | 'fr' | 'pt';
24+
}
25+
}
26+
```
27+
28+
- `descriptionLanguage`: controls the language to which images will get converted to.
29+
30+
:::caution
31+
32+
This option works on a _best-effort_ basis: it is not guaranteed that the resulting text will be in the desired language.
33+
34+
:::
35+
36+
### HTML
37+
38+
```typescript
39+
{
40+
html?: {
41+
images?: {
42+
convert?: boolean;
43+
descriptionLanguage?: 'en' | 'it' | 'de' | 'es' | 'fr' | 'pt';
44+
maxConvertedImages?: number;
45+
convertOGImage?: boolean;
46+
}
47+
}
48+
}
49+
```
50+
- `convert`: Whether to convert any embedded images or not. Here, _embedded_ means an image that is specified using a [`data:` URL](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data). Images specified with normal links will not be included in the final converted output.
51+
52+
- `descriptionLanguage`: controls the language to which _embedded_ images will get converted to.
53+
54+
:::caution
55+
56+
This option works on a _best-effort_ basis: it is not guaranteed that the resulting text will be in the desired language.
57+
58+
:::
59+
60+
- `maxConvertedImages`: controls the max number of images converted per file, up to a global limit of 10 per file.
61+
62+
- `convertOGImage`: whether images present in an [Open Graph](https://ogp.me/) image meta tag (`<meta property="og:image" content="..." />`) should be converted. These support all types of images, including _embedded_ and "regular" images. Successfully converting this image will not count towards the embedded image conversion limit.
63+
64+
### PDF
65+
66+
```typescript
67+
{
68+
pdf?: {
69+
metadata?: boolean;
70+
images: {
71+
descriptionLanguage: 'en' | 'it' | 'de' | 'es' | 'fr' | 'pt';
72+
convert?: boolean;
73+
maxConvertedImages?: number;
74+
}
75+
}
76+
}
77+
```
78+
79+
- `metadata`: Previously, all converted PDF files always included metadata information when converted. This options allows you to opt-out of this behavior.
80+
81+
- `convert`: Whether to convert any embedded images or not.
82+
83+
- `descriptionLanguage`: controls the language to which _embedded_ images will get converted to.
84+
85+
:::caution
86+
87+
This option works on a _best-effort_ basis: it is not guaranteed that the resulting text will be in the desired language.
88+
89+
:::
90+
91+
- `maxConvertedImages`: controls the max number of images converted per file, up to a global limit of 10 per file.
92+
93+
94+
### DOCX
95+
96+
```typescript
97+
{
98+
docx?: {
99+
images?: {
100+
descriptionLanguage?: 'en' | 'it' | 'de' | 'es' | 'fr' | 'pt';
101+
convert?: boolean;
102+
maxConvertedImages?: number;
103+
}
104+
}
105+
}
106+
```
107+
108+
- `convert`: Whether to convert any embedded images or not.
109+
110+
- `descriptionLanguage`: controls the language to which _embedded_ images will get converted to.
111+
112+
:::caution
113+
114+
This option works on a _best-effort_ basis: it is not guaranteed that the resulting text will be in the desired language.
115+
116+
:::
117+
118+
- `maxConvertedImages`: controls the max number of images converted per file, up to a global limit of 10 per file.
119+
120+
## Examples
121+
122+
### Binding
123+
124+
To configure custom options, pass a `conversionOptions` object inside the second argument of the binding call, like this:
125+
126+
```typescript
127+
await env.AI.toMarkdown(..., {
128+
conversionOptions: {
129+
html: { ... },
130+
pdf: { ... },
131+
...
132+
}
133+
})
134+
```
135+
136+
### REST API
137+
138+
Since the REST API uses file uploads, the request's `Content-Type` will be `multipart/form-data`. As such, include a new form field with your stringified object as a value:
139+
140+
```bash
141+
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown \
142+
-X POST \
143+
-H 'Authorization: Bearer {API_TOKEN}' \
144+
...
145+
-F 'conversionOptions={ "html": { ... }, ... }'
146+
```

‎src/content/docs/workers-ai/features/markdown-conversion/index.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Markdown Conversion
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 6
6+
group:
7+
badge: Beta
8+
---
9+
10+
import { Code, Type, MetaInfo, Details, Render } from "~/components";
11+
12+
[Markdown](https://en.wikipedia.org/wiki/Markdown) is essential for text generation and large language models (LLMs) in training and inference because it can provide structured, semantic, human, and machine-readable input. Likewise, Markdown facilitates chunking and structuring input data for better retrieval and synthesis in the context of RAGs, and its simplicity and ease of parsing and rendering make it ideal for AI Agents.
13+
14+
For these reasons, document conversion plays an important role when designing and developing AI applications. Workers AI provides the `toMarkdown` utility method that developers can use from the [`env.AI`](/workers-ai/features/markdown-conversion/usage/binding/) binding or the [REST APIs](/workers-ai/features/markdown-conversion/usage/rest-api/) for quick, easy, and convenient conversion and summary of documents in multiple formats to Markdown language.
15+
16+
## Pricing
17+
18+
`toMarkdown` is free for most format conversions. In some cases, like image conversion, it can use Workers AI models for object detection and summarization, which may incur additional costs if it exceeds the Workers AI free allocation limits. See the [pricing page](/workers-ai/platform/pricing/) for more details.

‎src/content/docs/workers-ai/features/markdown-conversion/supported-formats.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Supported Formats
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 3
6+
---
7+
8+
import { Render } from "~/components";
9+
10+
This list shows all rich-content formats that are currently supported for Markdown conversion and is updated frequently:
11+
12+
<Render file="markdown-conversion-support" product="workers-ai" />

‎src/content/docs/workers-ai/features/markdown-conversion.mdx‎ renamed to ‎src/content/docs/workers-ai/features/markdown-conversion/usage/binding.mdx‎

Lines changed: 27 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,33 @@
11
---
2-
title: Markdown Conversion
2+
title: Workers Binding
33
pcx_content_type: how-to
44
sidebar:
5-
order: 5
6-
badge:
7-
text: Beta
5+
order: 2
86
---
97

10-
import { Code, Type, MetaInfo, Details, Render } from "~/components";
8+
import {
9+
Badge,
10+
Description,
11+
Render,
12+
TabItem,
13+
Tabs,
14+
WranglerConfig,
15+
MetaInfo,
16+
Type,
17+
} from "~/components";
1118

12-
[Markdown](https://en.wikipedia.org/wiki/Markdown) is essential for text generation and large language models (LLMs) in training and inference because it can provide structured, semantic, human, and machine-readable input. Likewise, Markdown facilitates chunking and structuring input data for better retrieval and synthesis in the context of RAGs, and its simplicity and ease of parsing and rendering make it ideal for AI Agents.
19+
Cloudflare’s serverless platform allows you to run code at the edge to build full-stack applications with [Workers](/workers/). A [binding](/workers/runtime-apis/bindings/) enables your Worker or Pages Function to interact with resources on the Cloudflare Developer Platform.
1320

14-
For these reasons, document conversion plays an important role when designing and developing AI applications. Workers AI provides the `toMarkdown` utility method that developers can use from the [`env.AI`](/workers-ai/configuration/bindings/) binding or the REST APIs for quick, easy, and convenient conversion and summary of documents in multiple formats to Markdown language.
21+
To use our Markdown Conversion service directly from your Workers, create an AI binding either in the Cloudflare dashboard (refer to [AI bindings](/pages/functions/bindings/#workers-ai) for instructions), or you can update your [Wrangler file](/workers/wrangler/configuration/). Add the following to your Wrangler file:
22+
23+
<WranglerConfig>
24+
25+
```toml
26+
[ai]
27+
binding = "AI" # i.e. available in your Worker on env.AI
28+
```
29+
30+
</WranglerConfig>
1531

1632
## Methods
1733

@@ -24,6 +40,8 @@ Takes a document or list of documents in different formats and converts them to
2440
- <code>files</code>: <Type text="MarkdownDocument | MarkdownDocument[]" />- an instance of or an array of
2541
`MarkdownDocument`s.
2642

43+
- <code>conversionOptions</code>: <Type text="ConversionOptions" />- options that control how conversion happens. See [Conversion Options](/workers-ai/features/markdown-conversion/conversion-options/) for further details.
44+
2745
#### Return values
2846

2947
- <code>results</code>: <Type text="Promise<ConversionResult | ConversionResult[]>" />- An instance of or an array of
@@ -71,7 +89,7 @@ This method is similar to `env.AI.toMarkdown` except that it is exposed through
7189

7290
### async env.AI.toMarkdown().supported()
7391

74-
Returns a list of file formats that are currently supported for markdown conversion. See [Supported formats](#supported-formats) for the full list of file formats that can be converted into Markdown.
92+
Returns a list of file formats that are currently supported for markdown conversion. See [Supported formats](/workers-ai/features/markdown-conversion/supported-formats/) for the full list of file formats that can be converted into Markdown.
7593

7694
#### Return values
7795

@@ -88,12 +106,6 @@ Returns a list of file formats that are currently supported for markdown convers
88106
- The [mime type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) of files of this format
89107

90108

91-
## Supported formats
92-
93-
This is the list of support formats. We are constantly adding new formats and updating this table.
94-
95-
<Render file="markdown-conversion-support" product="workers-ai" />
96-
97109
## Example
98110

99111
### Converting files
@@ -181,28 +193,4 @@ results in
181193
},
182194
...
183195
]
184-
```
185-
186-
## REST API
187-
188-
In addition to the Workers AI [binding](/workers-ai/configuration/bindings/), you can use the [REST API](/workers-ai/get-started/rest-api/):
189-
190-
### Conversion
191-
192-
```bash
193-
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown \
194-
-H 'Authorization: Bearer {API_TOKEN}' \
195-
-F "files=@cat.jpeg" \
196-
-F "files=@somatosensory.pdf"
197-
```
198-
199-
### Supported formats
200-
201-
```bash
202-
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown/supported \
203-
-H 'Authorization: Bearer {API_TOKEN}' \
204-
```
205-
206-
## Pricing
207-
208-
`toMarkdown` is free for most format conversions. In some cases, like image conversion, it can use Workers AI models for object detection and summarization, which may incur additional costs if it exceeds the Workers AI free allocation limits. See the [pricing page](/workers-ai/platform/pricing/) for more details.
196+
```

‎src/content/docs/workers-ai/features/markdown-conversion/usage/index.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Usage
4+
sidebar:
5+
order: 2
6+
group:
7+
hideIndex: true
8+
---
9+
10+
import { DirectoryListing } from "~/components";
11+
12+
<DirectoryListing />

0 commit comments

Comments
 (0)