Documents

Convert Document

Convert a file to PDF, Word, HTML, Markdown, plain text, CSV, Excel or JSON, with the built-in converters or an external Gotenberg-compatible service.

Convert Document (doc_convert) turns a file into another format and saves the result as a new file. Documents (Word, PowerPoint, OpenDocument, PDF, HTML, Markdown, RTF, text) convert to PDF, Word, HTML, Markdown and text; spreadsheets (Excel, OpenDocument, CSV, a JSON list of objects) convert to CSV, Excel and JSON. The built-in converters are pure JavaScript; for a faithful Office → PDF copy, configure the external converter.

Inputs

Document (source): a file object, a list (the first file), a storage:// reference, a URL, base64 content or text (converted as plain text). See File inputs.

Options

Setting	Key	Default	What it does
Convert to	`target`	`pdf`	`pdf`, `docx`, `html`, `markdown`, `text`, `csv`, `xlsx` or `json`
Engine	`engine`	`auto`	PDF only. `auto`: the external converter for Office files (Word, Excel, PowerPoint, OpenDocument, RTF, and the 97–2003 formats) when `DOCUMENT_CONVERTER_URL` is set, otherwise the built-in renderer. `builtin`: always built in. `external`: always the external converter (also for HTML, Markdown, text and CSV)
Page size	`page_size`	`A4`	Built-in PDF: `A4` or `Letter`
Title	`title`	the document's title, else the file name	The heading of HTML output and the title of PDF and Word output (not shown in the designer)
Sheet	`sheet`	first sheet	CSV, Excel and JSON targets: which sheet to read
Range	`range`	used range	Spreadsheet range, as in Read Document (not shown in the designer)
Delimiter	`delimiter`	`,`	CSV output: `,`, `;`, tab or `\|`
Pages	`pages`	all	PDF and PowerPoint inputs: the pages or slides to convert (not shown in the designer)
OCR	`ocr`, `ocr_languages`	`off`, `eng`	Scanned PDFs and images, as in Read Document (not shown in the designer)
Output file name	`output_name`	the source's name	The extension is added
Output variable	`output_var`	`converted_file`

What converts to what

Target	From	Notes
PDF	Every readable format	Built in: text, headings, lists, tables, links and code, in standard fonts. A PDF input is returned unchanged
Word (`docx`)	Every readable format	Headings, paragraphs, bold / italic, lists, tables and links
HTML	Every readable format	A complete page with the title as its heading; the content is sanitised
Markdown	Every readable format	A Markdown input is returned unchanged
Text	Every readable format	The plain text Read Document gives
CSV	Excel, ODS, CSV, TSV, a JSON list of objects, or the first table of a document	The first sheet unless you choose one (a warning says when there were more)
Excel (`xlsx`)	Spreadsheets (every sheet), a JSON list of objects, or every table of a document (one sheet per table)
JSON	Spreadsheets (the rows; several sheets → an object keyed by sheet name), a JSON list of objects, or any document (`{ metadata, text, structure }`)

A document without a table cannot become CSV or Excel ("has no table to convert"), and the 97–2003 formats convert only to PDF, only with the external converter.

Outputs

{{converted_file}} is the new file as a file object; {{file}} and {{file_url}} are set too.

{
  "_file": true,
  "id": "0b7e4c2a-91d3-4f0e-8a65-3d2c1b9e7f40",
  "name": "Supply Agreement.pdf",
  "size": 5214,
  "mime_type": "application/pdf",
  "content_type": "application/pdf",
  "url": "https://tasks.example.com/files/task-files/workflow-files/<workspace-id>/0b7e4c2a-91d3-4f0e-8a65-3d2c1b9e7f40.pdf",
  "path": "workflow-files/<workspace-id>/0b7e4c2a-91d3-4f0e-8a65-3d2c1b9e7f40.pdf",
  "storage_ref": "storage://task-files/workflow-files/<workspace-id>/0b7e4c2a-91d3-4f0e-8a65-3d2c1b9e7f40.pdf",
  "uploaded_by": null,
  "uploaded_at": "2026-10-28T09:20:41.106Z",
  "checksum_sha256": "a3c91f0e7b2d4c6e8f1a3b5c7d9e0f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c0d2e"
}

The run history shows the conversion and the engine used:

json

{ "variable": "converted_file", "from": "docx", "to": "pdf", "engine": "builtin", "file": "Supply Agreement.pdf", "size": 5214, "warnings": ["Built-in PDF output keeps the text, headings, lists and tables but not the original layout; configure DOCUMENT_CONVERTER_URL for a faithful copy"] }

On the canvas

The target format, and (external) when the engine is forced: → PDF, → XLSX, → PDF (external).

Limits

Built-in PDF output uses the standard PDF fonts, which cover Latin text (Windows-1252) only. Other characters — Greek, Cyrillic, CJK, most symbols and emoji — are replaced with "?" and the run logs a warning. Use the external converter for other scripts.
Built-in Office → PDF keeps the content, not the layout: text, headings, lists and tables come across; fonts, columns, headers and footers, images and page layout do not.
Reading the source follows the read limits; a conversion has twice DOCUMENT_TIMEOUT_SECONDS, and the external converter DOCUMENT_CONVERTER_TIMEOUT_SECONDS (120) per call.

Security notes

HTML output is sanitised. The external converter receives only the file being converted, at the address an administrator configured (DOCUMENT_CONVERTER_URL, with an optional DOCUMENT_CONVERTER_TOKEN); its answer must be a PDF. Run it on your own network, never a public service.

Example

json

{
  "type": "doc_convert",
  "label": "Contract to PDF",
  "config": {
    "source": "{{contract}}",
    "target": "pdf",
    "page_size": "A4",
    "output_name": "Supply agreement {{contract_number}}",
    "output_var": "contract_pdf"
  }
}

Canvas: → PDF.

Works well with

Word Document (fill a template) → Convert Document (PDF) → PDF Tools (stamp "APPROVED") → Send Email.
Read Document when you need the rows or text rather than a file.
Convert a workbook to CSV for an HTTP Request to a system that only takes CSV.