@mazix/n8n-nodes-converter-documents
Version:
n8n node to convert various document formats (DOCX, DOC, XML, YML, XLSX, CSV, PDF, TXT, PPT, PPTX, HTML, JSON, ODT, ODP, ODS) to JSON or text format
270 lines (209 loc) • 7.86 kB
Markdown
# n8n Document Converter Node
[](https://www.npmjs.com/package/@mazix/n8n-nodes-converter-documents)
[](LICENSE)
[](https://github.com/mazixs/n8n-node-converter-documents)
[](https://www.typescriptlang.org/)
[](https://n8n.io/)
> **n8n community node** for converting documents to JSON/text. Supports 15+ formats with AI-friendly output.
## Table of Contents
- [Supported Formats](#supported-formats)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Output Examples](#output-examples)
- [Architecture](#architecture)
- [Development](#development)
- [License](#license)
## Supported Formats
| Category | Formats | Details |
|----------|---------|---------|
| **Documents** | DOCX, DOC, ODT, TXT, PDF | Text, HTML, or Markdown output for DOCX |
| **Spreadsheets** | XLSX, ODS, CSV | Multi-sheet parsing for XLSX/ODS and CSV |
| **Presentations** | PPTX, PPT, ODP | Text extraction |
| **Web & Data** | HTML, HTM, XML, JSON | Structure-aware parsing |
| **E-commerce** | YML (Yandex Market) | Specialized shop/offers/categories parsing |
## Features
**Core**
- Automatic file type detection via magic bytes
- Strategy pattern: each format has its own processing pipeline
- DOCX output: plain text (default), HTML, or **Markdown** (GFM tables, headings, bold/italic)
- DOCX → Markdown ideal for AI/LLM/RAG pipelines
- XLSX multi-sheet processing with Excel-style column names (A, B, C...)
- JSON flattening for nested structures
- YML (Yandex Market) specialized parser
- `usableAsTool: true` for n8n AI Agent integration
**Reliability**
- Concurrency control via promise pool (Set-based, no race conditions)
- Fallback chains: DOCX uses officeparser -> mammoth, DOC/PPT uses CFB signature check + officeparser
- File name sanitization (path traversal protection)
- Configurable file size limits (up to 100MB)
- Custom error classes with descriptive messages
## Installation
### Via n8n UI (recommended)
```
Settings -> Community nodes -> Install
Package name: @mazix/n8n-nodes-converter-documents
```
### Via CLI
```bash
cd ~/.n8n
npm install @mazix/n8n-nodes-converter-documents
# Restart n8n
```
### Manual
```bash
git clone https://github.com/mazixs/n8n-node-converter-documents.git
cd n8n-node-converter-documents
npm install
npm run build
# Copy dist/ and package.json to ~/.n8n/custom-nodes/n8n-node-converter-documents/
```
## Usage
1. Add **"Convert File to JSON"** node to your workflow
2. Connect a node that provides binary data (e.g., Read Binary File, HTTP Request)
3. Configure parameters:
| Parameter | Default | Description |
|-----------|---------|-------------|
| **Binary Property** | `data` | Name of the binary property with the file |
| **Output Format (DOCX)** | `text` | `text`, `html`, or `markdown` (GFM with tables) |
| **Max File Size (MB)** | `50` | File size limit |
| **Max Concurrency** | `4` | Parallel file processing |
## Output Examples
### Text document (DOCX, PDF, TXT, etc.)
```json
{
"text": "Extracted document content...",
"metadata": {
"fileName": "report.docx",
"fileSize": 12345,
"fileType": "docx",
"processedAt": "2026-02-08T00:00:00.000Z"
}
}
```
### DOCX with HTML output
```json
{
"text": "<p>Introduction</p><table><tr><td>Name</td><td>Value</td></tr>...</table>",
"metadata": { "fileName": "data.docx", "fileType": "docx" }
}
```
### DOCX with Markdown output
```json
{
"text": "# Introduction\n\n| Name | Value |\n| --- | --- |\n| Item | 100 |\n\n**Bold text** and _italic_",
"metadata": { "fileName": "data.docx", "fileType": "docx" }
}
```
### XLSX (multi-sheet)
```json
{
"sheets": {
"Products": [
{ "A": "ID", "B": "Name", "C": "Price" },
{ "A": 1, "B": "Apple", "C": 100 }
],
"Orders": [
{ "A": "Order", "B": "Qty" },
{ "A": 101, "B": 5 }
]
},
"metadata": { "fileName": "data.xlsx", "fileType": "xlsx" }
}
```
### JSON (flattened)
```json
{
"text": "{\n \"user.name\": \"John\",\n \"user.address.city\": \"London\"\n}",
"warning": "Multi-level JSON structure was converted to flat object"
}
```
### YML (Yandex Market)
```json
{
"text": "{ \"shop\": { \"name\": \"MyShop\" }, \"currencies\": [...], \"categories\": [...], \"offers\": [...] }"
}
```
## Architecture
### Project Structure
```
src/
├── FileToJsonNode.node.ts # Node class (~220 lines)
├── types.ts # Interfaces (JsonResult, StrategyFn, YML types)
├── errors.ts # Custom error classes
├── helpers.ts # extractViaOfficeParser, limitExcelSheet
├── strategies/
│ └── index.ts # All format strategies
├── processors/
│ └── yml.ts # Yandex Market YML processor
└── utils/
├── sanitize.ts # File name sanitization
├── promisePool.ts # Concurrency control (Set-based)
├── columns.ts # numberToColumn (1→A, 27→AA)
├── flatten.ts # JSON flattening
└── index.ts # Barrel export
```
### Processing Flow
```
Input binary → detect file type (magic bytes) → select strategy → process → output JSON
│
┌────────────────────────┼────────────────────┐
│ │ │
Text formats Spreadsheets Special
(DOCX, PDF, TXT, (XLSX, CSV, ODS) (XML, JSON,
PPTX, HTML, ODT, YML, HTML)
ODP, DOC, PPT)
```
### Technology Stack
| Component | Library | Version |
|-----------|---------|---------|
| DOCX/PDF/PPTX/OD* | officeparser | ^6.0.4 |
| DOCX (HTML/MD) | mammoth | ^1.11.0 |
| HTML → Markdown | node-html-markdown | ^2.0.0 |
| XLSX | read-excel-file | ^6.0.3 |
| CSV | papaparse | ^5.5.3 |
| XML/YML | fast-xml-parser | ^5.3.4 |
| HTML | node-html-parser | ^7.0.2 |
| Encoding | chardet | ^2.1.1 |
| File type | file-type | 16.5.4 |
| n8n SDK | n8n-workflow | ^2.7.0 |
| Runtime | Node.js | 22.x |
| Language | TypeScript | 5.8 (strict) |
| Tests | Jest | 30.x |
## Development
```bash
npm install # Install dependencies
npm run build # Compile TypeScript
npm test # Run 57 tests (13 suites)
npm run lint # ESLint check
npm run dev # Watch mode
npm run test:coverage # Coverage report
```
### CI/CD
- **CI** (`ci.yml`): lint -> build -> test -> security audit on push/PR to main/develop
- **Auto Release** (`auto-release.yml`): creates GitHub Release + git tag on version bump in main
- **npm publish**: manual (`npm publish --access public`)
## Limitations
| Limitation | Details |
|------------|---------|
| **Legacy XLS** | Binary Excel not supported, convert to XLSX |
| **file-type** | Pinned to v16.5.4 (last CJS version, v17+ is ESM-only) |
| **Scanned PDFs** | Image-based PDFs return empty text (no OCR) |
| **Large files** | PDF/XLSX load into RAM; use Max File Size to control |
## License
[MIT](LICENSE) © mazix
## Links
- [npm](https://www.npmjs.com/package/@mazix/n8n-nodes-converter-documents)
- [GitHub](https://github.com/mazixs/n8n-node-converter-documents)
- [Changelog](CHANGELOG.md)