cb8f57c12b
Add --sheet parameter to specify worksheets by name or index (1-based). Change default behavior to use first worksheet instead of active sheet, with proper error messages for invalid worksheet references. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
140 lines
4.4 KiB
Markdown
140 lines
4.4 KiB
Markdown
---
|
|
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
|
|
```
|