Description

📄 n8n Document Converter Node

🚀 n8n community node for converting various document formats to JSON/text with AI-friendly output

📑 Table of Contents

• Features
• Supported Formats
• DOCX to HTML Conversion
• XLSX Multi-Sheet Processing
• Installation
• Usage Examples
• Architecture
• Development
• Latest Updates
• Documentation

✨ Features

📚 Supported Formats

*Legacy formats require conversion to modern formats (DOCX, PPTX, XLSX)

📊 DOCX to HTML Conversion (v1.0.21+)

Latest: Node renamed to "Document Converter" in v1.0.22

🎨 Choose Your Output Format

📋 Usage in n8n

1. Add "Document Converter" node
2. Select "Output Format (DOCX)" parameter:
   • Plain Text → Simple extraction
   • HTML → Tables + formatting preserved

💡 Example Output

{
  "text": "Situation: Often search by one field\nAction: Create index on that field"
}

{
  "text": "<table><tr><td><strong>Situation</strong></td><td><strong>Action</strong></td></tr><tr><td>Often search by one field</td><td>Create index on that field</td></tr></table>"
}

🎯 HTML Format Features

✨ Enhanced Controls

🧠 HTML Table Preservation

When converting HTML or DOCX (in HTML mode), tables are now preserved in the output. This is critical for RAG/LLM contexts, allowing AI models to understand structured data instead of flattened text.

⚙️ Advanced CSV & Excel Control

• CSV Delimiter: Manually select , ; \t | or keep Auto.
• Max Excel Rows: Limit rows per sheet (e.g., 1000) to prevent memory crashes on huge files.

📊 XLSX Multi-Sheet Processing

🗂️ How It Works

{
  "sheets": {
    "Products": [
      { "A": "ID", "B": "Name", "C": "Price" },
      { "A": 1, "B": "Apple", "C": 100 },
      { "A": 2, "B": "Banana", "C": 50 }
    ],
    "Orders": [
      { "A": "Order", "B": "Quantity" },
      { "A": 101, "B": 5 }
    ]
  }
}

📌 Key Features

🚀 Installation

Option 1: npm Package (Recommended)

Via n8n web interface:

Settings → Community nodes → Install
Package name: @mazix/n8n-nodes-converter-documents

Or via command line:

npm install @mazix/n8n-nodes-converter-documents

Option 2: Standalone Version

# 1. Clone and build
git clone https://github.com/mazixs/n8n-node-converter-documents.git
cd n8n-node-converter-documents
npm install
npm run standalone

# 2. Copy to n8n
cp -r ./standalone ~/.n8n/custom-nodes/n8n-node-converter-documents
cd ~/.n8n/custom-nodes/n8n-node-converter-documents
npm install

# 3. Restart n8n

Option 3: Manual Installation

mkdir -p ~/.n8n/custom-nodes/n8n-node-converter-documents
cp dist/*.js dist/*.svg ~/.n8n/custom-nodes/n8n-node-converter-documents/
cp package.json ~/.n8n/custom-nodes/n8n-node-converter-documents/
cd ~/.n8n/custom-nodes/n8n-node-converter-documents
npm install --production

📖 Usage Examples

Text Document Output

{
  "text": "Extracted text content...",
  "metadata": {
    "fileName": "document.docx",
    "fileSize": 12345,
    "fileType": "docx",
    "processedAt": "2024-06-01T12:00:00.000Z"
  }
}

Excel Spreadsheet Output

{
  "sheets": {
    "Sheet1": [
      { "A": "Name", "B": "Age", "C": "City" },
      { "A": "Alice", "B": 30, "C": "New York" },
      { "A": "Bob", "B": 25, "C": "London" }
    ]
  },
  "metadata": {
    "fileName": "data.xlsx",
    "fileSize": 23456,
    "fileType": "xlsx"
  }
}

JSON Normalization

Input:

{
  "user": {
    "name": "John",
    "address": { "city": "London" }
  }
}

Output (flattened):

{
  "text": "{\n  \"user.name\": \"John\",\n  \"user.address.city\": \"London\"\n}",
  "warning": "Multi-level JSON structure was converted to flat object"
}

🏗️ Architecture

Strategy Pattern Implementation

DOCX Processing Flow:
┌─────────────────────────────────────┐
│ 1. If outputFormat === 'html':     │
│    → mammoth.convertToHtml()       │
│    → [Success] Return HTML          │
│    → [Fail] Fallback to text       │
│                                     │
│ 2. Text mode (default):            │
│    → officeparser (primary)        │
│    → mammoth.extractRawText (fb)   │
│    → XML direct parsing (last)     │
└─────────────────────────────────────┘

Technology Stack

Security Features

💻 Development

Quick Start

npm install        # Install dependencies
npm run dev        # Watch mode
npm run build      # Compile
npm test           # Run 80 tests
npm run lint       # Check code quality

Build Commands

Project Structure

├── src/
│   ├── FileToJsonNode.node.ts  # Main node (Strategy Pattern)
│   ├── helpers.ts               # Utilities
│   └── errors.ts                # Custom errors
├── test/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── samples/                 # Test files
├── docs/                        # Documentation
│   ├── SOLUTION.md
│   ├── HTML_CONVERSION_PLAN.md
│   └── MAMMOTH_ANALYSIS.md
└── dist/                        # Compiled output

📈 Latest Updates

🎉 v1.1.2 (Current – 2025-11-29)

What's New in 1.1.x:

+ Preserve Tables: DOCX/HTML tables retained for AI context
+ Metadata Extraction: Get author/date from docs
+ 10x Faster: XML/YML parsing with fast-xml-parser
+ Memory Optimization: node-html-parser replaces cheerio
+ Reliability: Robust Promise Pool and file-type fixes

Previous Versions

📚 Documentation

🔧 Troubleshooting

Common Issues

Error: Cannot find module 'exceljs'

# Solution 1: Use standalone version (recommended)
npm run standalone

# Solution 2: Check dependencies
cd ~/.n8n/custom-nodes/n8n-node-converter-documents
npm list
npm install

Large files causing OOM

• Split files into smaller parts
• Reduce maxFileSize parameter
• Use streaming for CSV/TXT formats

⚠️ Limitations

📊 Statistics

• 12+ file formats supported
• 80 tests passing
• 5 specialized parsers
• 10K rows per sheet limit
• 100MB max file size
• 0 critical vulnerabilities

🤝 Contributing

Issues and pull requests are welcome!

📝 License

MIT © mazix

🔗 Links

• npm Package
• GitHub Repository
• n8n Community