xlsx2md

A Node.js library for converting OpenXML spreadsheet documents (.xlsx) to Pandoc-compatible Markdown grid tables.

Installation

npm install xlsx2md

Features

• Convert Excel worksheets to Pandoc Markdown grid table format
• List all sheet names in a workbook
• Select specific sheets for conversion
• Custom table titles for each sheet
• Batch conversion of multiple sheets
• Preserves cell formatting (bold, italic, alignment)
• Handles merged cells
• Supports multi-line content within cells
• Outputs Pandoc metadata for advanced formatting

API

convert(archiveData, lineWidth, configString)

Converts an Excel workbook to Markdown.

Parameters:

| Parameter | Type | Description | |----------------|--------------|-----------------------------------------| | archiveData | Uint8Array | Binary content of the .xlsx file | | lineWidth | number | Maximum line width for table formatting | | configString | string | XML configuration string (see below) |

Returns: string - Markdown output with Pandoc metadata

list(archiveData)

Lists all sheet names in the workbook.

Parameters:

| Parameter | Type | Description | |---------------|--------------|------------------------------------| | archiveData | Uint8Array | Binary content of the .xlsx file |

Returns: string[] - Array of sheet names

Configuration

The configuration is provided as an XML string with the following structure:

<?xml version="1.0" encoding="utf-8" ?>
<xlsx2md>
    <SheetLoader>
        <!-- Convert a specific sheet by name -->
        <Sheet name="SheetName">
            <Title><![CDATA[Table Title]]></Title>
        </Sheet>

        <!-- Convert the default (first) sheet -->
        <Sheet name="">
            <Title><![CDATA[Default Sheet Title]]></Title>
        </Sheet>
    </SheetLoader>
</xlsx2md>

Configuration Options:

| Element | Attribute | Description | |-----------|-----------|----------------------------------------------------------------------------| | <Sheet> | name | Sheet name to convert. Use empty string "" for the default (first) sheet | | <Title> | - | Optional table title. Can be empty or omitted |

Usage Examples

Basic Conversion

const xlsx2md = require('xlsx2md');
const fs = require('fs');

// Read the Excel file
const archive = fs.readFileSync('./example.xlsx');

// Configure the conversion
const configString = `<?xml version="1.0" encoding="utf-8" ?>
<xlsx2md>
    <SheetLoader>
        <Sheet name="Sales Data">
            <Title><![CDATA[2024 Sales Report]]></Title>
        </Sheet>
    </SheetLoader>
</xlsx2md>`;

// Convert to Markdown
const result = xlsx2md.convert(archive, 80, configString);

// Write output
fs.writeFileSync('./output.md', result, {encoding: 'utf-8'});

List Sheet Names

const xlsx2md = require('xlsx2md');
const fs = require('fs');

const archive = fs.readFileSync('./example.xlsx');
const sheetNames = xlsx2md.list(archive);

console.log('Available sheets:', sheetNames);

Convert Default Sheet

const xlsx2md = require('xlsx2md');
const fs = require('fs');

const archive = fs.readFileSync('./example.xlsx');

const configString = `<?xml version="1.0" encoding="utf-8" ?>
<xlsx2md>
    <SheetLoader>
        <Sheet name="">
            <Title><![CDATA[First Sheet]]></Title>
        </Sheet>
    </SheetLoader>
</xlsx2md>`;

const result = xlsx2md.convert(archive, 80, configString);
console.log(result);

Batch Convert Multiple Sheets

const xlsx2md = require('xlsx2md');
const fs = require('fs');

const archive = fs.readFileSync('./example.xlsx');

const configString = `<?xml version="1.0" encoding="utf-8" ?>
<xlsx2md>
    <SheetLoader>
        <Sheet name="Q1 Data">
            <Title><![CDATA[Q1 Report]]></Title>
        </Sheet>
        <Sheet name="Q2 Data">
            <Title><![CDATA[Q2 Report]]></Title>
        </Sheet>
        <Sheet name="Q3 Data">
            <Title><![CDATA[Q3 Report]]></Title>
        </Sheet>
        <Sheet name="Q4 Data">
            <Title><![CDATA[Q4 Report]]></Title>
        </Sheet>
    </SheetLoader>
</xlsx2md>`;

const result = xlsx2md.convert(archive, 80, configString);
fs.writeFileSync('./quarterly_reports.md', result, {encoding: 'utf-8'});

Convert Without Title

const xlsx2md = require('xlsx2md');
const fs = require('fs');

const archive = fs.readFileSync('./example.xlsx');

const configString = `<?xml version="1.0" encoding="utf-8" ?>
<xlsx2md>
    <SheetLoader>
        <Sheet name="Data">
            <Title><![CDATA[]]></Title>
        </Sheet>
    </SheetLoader>
</xlsx2md>`;

const result = xlsx2md.convert(archive, 80, configString);
console.log(result);

Output Format

The library outputs Pandoc-compatible Markdown with:

1. Metadata block - Contains table alignment settings and cell content references
2. Grid tables - Uses Pandoc's grid table syntax with proper borders

Example output:

---
'meta-Default (1st) sheet in workbook':
  '@align-r2c2': 'AlignLeft'
  '@align-r2c4': 'AlignRight'
  '@align-r3c2': 'AlignLeft'
  '@align-r3c4': 'AlignRight'
  '@align-r4c2': 'AlignLeft'
  '@align-r4c4': 'AlignRight'
  '@align-r5c2': 'AlignRight'
  '@align-r6c2': 'AlignRight'
  '@align-r7c1': 'AlignRight'
  '@align-r8c2': 'AlignRight'
  '@align-r9c2': 'AlignRight'
  'B1': |
    **Unit Name**
---

Table: Default (1st) sheet
in workbook

+:--------:+:-------------:+:--------------:+:--------------------------------:+
|**№**     |{{B1}}         |**Amount**      |**Unit Price**               |
+----------+---------------+----------------+----------------------------------+
|1         |Unit A    |1               |$100\.00                          |
+----------+---------------+----------------+----------------------------------+
|2         |Unit B    |2               |$2\,000\,000\.00                  |
+----------+---------------+----------------+----------------------------------+
|3         |Unit C    |3               |$300\.58                          |
+----------+---------------+----------------+----------------------------------+
|**Original Price**                    |**$2\,000\,400\.58**              |
+----------+---------------+----------------+----------------------------------+
|**Discount**                               |**30\.3%**                        |
+                                           +----------------------------------+
|                                           |**\-$606\,782**                   |
+----------+---------------+----------------+----------------------------------+
|**Current Price**                     |**$1\,393\,619\.07**              |
+----------+---------------+----------------+----------------------------------+
|**Expiration Date**                   |2023/10/1 09\:16\:01\.982    |
+----------+---------------+----------------+----------------------------------+

Error Handling

The library throws errors for:

• Invalid archive format (not a valid .xlsx file)
• Sheet name not found in the workbook
• Malformed configuration XML

try {
    const result = xlsx2md.convert(archive, 80, configString);
} catch (error) {
    console.error('Conversion failed:', error.message);
}

License

MIT