---
name: excel-to-markdown
description: Convert Excel (.xlsx, .xls) files to Markdown table format. Use for converting Excel documents to Markdown for display or documentation, extracting and analyzing Excel data in a structured format, processing Excel files with automatic data range detection, generating Markdown tables with optional row/column numbering, or handling partial conversions with specific row/column ranges. Triggered by requests like "convert this Excel to Markdown", "export Excel as MD", "analyze this spreadsheet", or when working with .xlsx/.xls files that need to be viewed or processed as text.
---

# Excel to Markdown Converter

## Overview

Convert Excel spreadsheets to Markdown table format with automatic data range detection and flexible output options. The converter handles complex multi-sheet workbooks, preserves cell formatting, and can display row/column numbers for easy reference.

## Quick Start

### Basic Conversion

Convert an entire Excel file to Markdown:

```bash
python3 scripts/excel_to_markdown.py input.xlsx -o output.md
```

### Specify Worksheet

Convert a specific worksheet by name or index:

```bash
# By worksheet name
python3 scripts/excel_to_markdown.py input.xlsx -o output.md --sheet "Sheet2"

# By worksheet index (1-based)
python3 scripts/excel_to_markdown.py input.xlsx -o output.md --sheet 2
```

### Convert with Row/Column Numbers

Display Excel row and column identifiers for reference:

```bash
python3 scripts/excel_to_markdown.py input.xlsx -o output.md --show-rows --show-cols
```

### Specify Data Range

Convert only a specific portion of the spreadsheet:

```bash
# Convert first 10 rows and 5 columns
python3 scripts/excel_to_markdown.py input.xlsx -o output.md -r 10 -c 5

# Start from row 2, column 3, convert 20 rows
python3 scripts/excel_to_markdown.py input.xlsx -o output.md --start-row 2 --start-col 3 -r 20
```

## Command Line Options

| Option | Description |
|--------|-------------|
| `input_file` | Path to the Excel file (required) |
| `-o, --output` | Output Markdown file path (optional, prints to console if not specified) |
| `-r, --max-rows` | Maximum number of rows to convert (auto-detect if not specified) |
| `-c, --max-cols` | Maximum number of columns to convert (auto-detect if not specified) |
| `--show-rows` | Display row numbers in the first column |
| `--show-cols` | Display column letters (A, B, C...) in the first row |
| `--start-row` | Starting row number (default: 1) |
| `--start-col` | Starting column number (default: 1) |
| `--sheet` | Worksheet name or index (default: first worksheet) |

## Features

### Automatic Data Range Detection

The converter automatically scans the spreadsheet to identify the actual data range (up to 100 rows and 100 columns by default), ignoring empty trailing rows and columns.

### Cell Content Handling

- Empty cells are rendered as blank
- Pipe characters (`|`) in cell content are escaped as `\|`
- Newlines within cells are converted to `<br>` tags
- All cell values are trimmed of leading/trailing whitespace

### Multi-Sheet Support

By default, the converter processes the first worksheet in the workbook. You can specify a different worksheet using the `--sheet` parameter:

- **By name**: `--sheet "Sheet2"` or `--sheet "Data"`
- **By index**: `--sheet 2` (1-based indexing)

If the specified worksheet is not found, an error will display the list of available worksheets.

## Common Use Cases

### 1. Data Analysis

Extract Excel data for analysis or processing:

```bash
python3 scripts/excel_to_markdown.py sales_data.xlsx -o sales_analysis.md
```

Then analyze the Markdown output or provide insights based on the structured data.

### 2. Documentation

Convert spreadsheets to Markdown for inclusion in documentation:

```bash
python3 scripts/excel_to_markdown.py specifications.xlsx -o specs.md --show-rows --show-cols
```

The row/column numbers make it easy to reference specific cells in documentation.

### 3. Quick Preview

Quickly view Excel contents without opening a spreadsheet application:

```bash
python3 scripts/excel_to_markdown.py report.xlsx
```

### 4. Partial Data Extraction

Extract specific sections from large spreadsheets:

```bash
# Get header row and first 10 data rows
python3 scripts/excel_to_markdown.py large_file.xlsx -o sample.md -r 11
```

## Script Location

The converter script is located at: `scripts/excel_to_markdown.py`

## Dependencies

The script requires `openpyxl` for Excel file processing:

```bash
pip install openpyxl
```