> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/markitdown/llms.txt
> Use this file to discover all available pages before exploring further.

# Other Formats

> Convert CSV, JSON, XML, ZIP archives, EPUB books, and Jupyter notebooks to Markdown

MarkItDown supports various additional file formats for data, archives, and structured documents.

## Supported Formats

<CardGroup cols={3}>
  <Card title="CSV" icon="table">
    Comma-separated values
  </Card>

  <Card title="JSON" icon="code">
    JSON and JSONL files
  </Card>

  <Card title="XML" icon="file-code">
    XML documents via RSS parser
  </Card>

  <Card title="ZIP" icon="file-zipper">
    Archive file contents
  </Card>

  <Card title="EPUB" icon="book">
    E-book format
  </Card>

  <Card title="Jupyter" icon="calculator">
    IPython notebooks
  </Card>
</CardGroup>

## CSV Files

### Dependencies

No external dependencies - uses Python's built-in `csv` module.

### Features

* Converts CSV to Markdown tables
* First row treated as header
* Automatic encoding detection with `charset-normalizer`
* Handles irregular row lengths

### Usage

<CodeGroup>
  ```python Python theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("data.csv")
  print(result.markdown)
  ```

  ```bash CLI theme={null}
  markitdown data.csv > table.md
  ```
</CodeGroup>

### Example

**Input CSV**:

```csv theme={null}
Name,Age,City
John Doe,30,New York
Jane Smith,25,Los Angeles
Bob Johnson,35,Chicago
```

**Output Markdown**:

```markdown theme={null}
| Name | Age | City |
| --- | --- | --- |
| John Doe | 30 | New York |
| Jane Smith | 25 | Los Angeles |
| Bob Johnson | 35 | Chicago |
```

### Implementation

* **Converter Class**: `CsvConverter` (`_csv_converter.py`)
* **Accepted Extensions**: `.csv`
* **MIME Types**: `text/csv`, `application/csv`
* **Encoding**: Uses `charset-normalizer` if charset not specified

## JSON Files

### Dependencies

No external dependencies - uses Python's built-in `json` module.

### Features

* Plain text output (not converted to structured Markdown)
* Preserves JSON formatting
* Supports both `.json` and `.jsonl` files

### Usage

<CodeGroup>
  ```python Python theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("data.json")
  print(result.markdown)  # Raw JSON text
  ```

  ```bash CLI theme={null}
  markitdown config.json
  ```
</CodeGroup>

### Implementation

* **Converter Class**: `PlainTextConverter` (`_plain_text_converter.py`)
* **Accepted Extensions**: `.json`, `.jsonl`
* **MIME Types**: `application/json`
* **Processing**: Treated as plain text, no special JSON parsing

<Info>
  JSON files are processed as plain text. For structured JSON-to-Markdown conversion, consider pre-processing with `jq` or a custom script.
</Info>

## XML Files

### Dependencies

```bash theme={null}
pip install beautifulsoup4 defusedxml
```

### Features

* XML files are processed by the RSS converter
* Only RSS/Atom feeds are specially formatted
* Other XML treated as plain text

### Usage

<CodeGroup>
  ```python RSS/Atom XML theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("feed.xml")
  print(result.markdown)  # Formatted feed content
  ```

  ```python Generic XML theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("config.xml")
  print(result.markdown)  # Plain text XML
  ```
</CodeGroup>

### Implementation

* **RSS/Atom XML**: `RssConverter` (`_rss_converter.py`) - see [Web Content](/formats/web-content#rssatom-feeds)
* **Other XML**: `PlainTextConverter` (`_plain_text_converter.py`)

## ZIP Archives

### Dependencies

No external dependencies - uses Python's built-in `zipfile` module.

### Features

* Extracts and converts each file in the archive
* Recursively processes nested files
* Skips unsupported formats silently
* Preserves file paths in output

### Usage

<CodeGroup>
  ```python Python theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("archive.zip")
  print(result.markdown)
  ```

  ```bash CLI theme={null}
  markitdown project.zip > contents.md
  ```
</CodeGroup>

### Output Format

```markdown theme={null}
Content from the zip file `archive.zip`:

## File: README.md

# Project Title

Project description here...

## File: docs/guide.docx

# User Guide

Welcome to the user guide...

## File: data/results.csv

| Name | Value | Status |
|------|-------|--------|
| Test1 | 42 | Pass |
| Test2 | 37 | Pass |

## File: images/logo.png

ImageSize: 512x512
DateTimeOriginal: 2024:02:15 10:00:00
```

### Implementation

* **Converter Class**: `ZipConverter` (`_zip_converter.py`)
* **Accepted Extensions**: `.zip`
* **MIME Types**: `application/zip`
* **Processing**: Each file converted independently using appropriate converter

### Advanced Example

```python theme={null}
from markitdown import MarkItDown
from openai import OpenAI

# ZIP with images - use LLM for image descriptions
client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    exiftool_path="/usr/local/bin/exiftool"
)

result = md.convert("photos.zip")
print(result.markdown)  # Includes image descriptions
```

## EPUB Books

### Dependencies

```bash theme={null}
pip install beautifulsoup4 defusedxml
```

### Features

* Extracts book metadata (title, authors, publisher, etc.)
* Converts chapters in reading order
* Preserves chapter structure
* Handles XHTML content

### Usage

<CodeGroup>
  ```python Python theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("book.epub")
  print(result.title)  # Book title
  print(result.markdown)  # Full book content
  ```

  ```bash CLI theme={null}
  markitdown novel.epub > novel.md
  ```
</CodeGroup>

### Output Format

```markdown theme={null}
**Title:** The Great Novel
**Authors:** Jane Author, John Writer
**Publisher:** Example Press
**Date:** 2024-01-15
**Language:** en
**Description:** An exciting tale of adventure and discovery.
**Identifier:** ISBN:978-0-123456-78-9

# Chapter 1: The Beginning

It was a dark and stormy night...

# Chapter 2: The Journey

The next morning, our hero set out...
```

### Implementation

* **Converter Class**: `EpubConverter` (`_epub_converter.py`)
* **Accepted Extensions**: `.epub`
* **MIME Types**: `application/epub`, `application/epub+zip`, `application/x-epub+zip`
* **Processing**:
  1. Extract `META-INF/container.xml` to find `content.opf`
  2. Parse metadata from `content.opf`
  3. Read spine order from `content.opf`
  4. Convert each chapter (XHTML) to Markdown
  5. Combine with metadata

### Metadata Fields

| Field         | Description      | Example               |
| ------------- | ---------------- | --------------------- |
| `title`       | Book title       | `The Great Gatsby`    |
| `authors`     | Author(s)        | `F. Scott Fitzgerald` |
| `language`    | Language code    | `en`, `es`, `fr`      |
| `publisher`   | Publisher name   | `Scribner`            |
| `date`        | Publication date | `1925-04-10`          |
| `description` | Book description | `A novel set in...`   |
| `identifier`  | ISBN or other ID | `ISBN:978-0-...`      |

## Jupyter Notebooks

### Dependencies

No external dependencies - uses Python's built-in `json` module.

### Features

* Converts `.ipynb` files to Markdown
* Preserves code cells in code blocks
* Includes markdown cells directly
* Extracts first H1 heading as title
* Handles raw cells

### Usage

<CodeGroup>
  ```python Python theme={null}
  from markitdown import MarkItDown

  md = MarkItDown()
  result = md.convert("analysis.ipynb")
  print(result.title)  # First H1 heading
  print(result.markdown)
  ```

  ```bash CLI theme={null}
  markitdown notebook.ipynb > notebook.md
  ```
</CodeGroup>

### Output Format

**Input Notebook**:

```json theme={null}
{
  "cells": [
    {
      "cell_type": "markdown",
      "source": ["# Data Analysis\n", "This notebook analyzes..."]
    },
    {
      "cell_type": "code",
      "source": ["import pandas as pd\n", "df = pd.read_csv('data.csv')"]
    },
    {
      "cell_type": "markdown",
      "source": ["## Results\n", "The analysis shows..."]
    }
  ]
}
```

**Output Markdown**:

````markdown theme={null}
# Data Analysis
This notebook analyzes...

```python
import pandas as pd
df = pd.read_csv('data.csv')
````

## Results

The analysis shows...

`````

### Implementation

- **Converter Class**: `IpynbConverter` (`_ipynb_converter.py`)
- **Accepted Extensions**: `.ipynb`
- **MIME Types**: `application/json` (with notebook content detection)
- **Cell Types**:
  - `markdown`: Included directly
  - `code`: Wrapped in ````python` code blocks
  - `raw`: Wrapped in ```` code blocks

### Advanced Example

```python
from markitdown import MarkItDown
import json

# Convert and extract title
md = MarkItDown()
result = md.convert("analysis.ipynb")

if result.title:
    print(f"Notebook: {result.title}")
    
# Count code cells
with open("analysis.ipynb") as f:
    notebook = json.load(f)
    code_cells = sum(1 for cell in notebook['cells'] if cell['cell_type'] == 'code')
    print(f"Code cells: {code_cells}")

# Save markdown
with open("analysis.md", "w") as f:
    f.write(result.markdown)
`````

## Plain Text Files

### Dependencies

No external dependencies.

### Features

* Supports `.txt`, `.text`, `.md`, `.markdown` extensions
* Automatic encoding detection
* Preserves content as-is

### Usage

```python theme={null}
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.txt")
print(result.markdown)  # Original text content
```

### Implementation

* **Converter Class**: `PlainTextConverter` (`_plain_text_converter.py`)
* **Accepted Extensions**: `.txt`, `.text`, `.md`, `.markdown`, `.json`, `.jsonl`
* **MIME Types**: `text/*`, `application/json`, `application/markdown`
* **Encoding**: Uses `charset-normalizer` if charset not specified

## Comparison Table

| Format     | Dependencies              | Structured Output | Metadata Support | Nested Content |
| ---------- | ------------------------- | ----------------- | ---------------- | -------------- |
| CSV        | None                      | ✓ (Tables)        | ✗                | ✗              |
| JSON       | None                      | ✗ (Plain text)    | ✗                | ✗              |
| XML        | BeautifulSoup, defusedxml | ✓ (RSS only)      | ✓ (RSS only)     | ✗              |
| ZIP        | None                      | ✓ (Per file)      | ✗                | ✓              |
| EPUB       | BeautifulSoup, defusedxml | ✓ (Chapters)      | ✓                | ✓              |
| Jupyter    | None                      | ✓ (Cells)         | ✓                | ✗              |
| Plain Text | None                      | ✗                 | ✗                | ✗              |

## Common Patterns

### Processing Archive Contents

```python theme={null}
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("project.zip")

# Extract individual file sections
sections = result.markdown.split("## File: ")
for section in sections[1:]:  # Skip header
    lines = section.split('\n')
    filename = lines[0]
    content = '\n'.join(lines[1:])
    print(f"File: {filename}")
    print(f"Content length: {len(content)} characters")
```

### CSV to Formatted Report

```python theme={null}
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("sales_data.csv")

# Wrap in document
report = f"""# Sales Report

Generated: {datetime.now().strftime('%Y-%m-%d')}

## Data

{result.markdown}

## Summary

Total entries: {result.markdown.count('|') - 2}
"""

with open("report.md", "w") as f:
    f.write(report)
```

### Book Chapter Extraction

```python theme={null}
from markitdown import MarkItDown
import re

md = MarkItDown()
result = md.convert("book.epub")

# Split by chapter headings
chapters = re.split(r'\n# ', result.markdown)

for i, chapter in enumerate(chapters[1:], 1):  # Skip metadata
    lines = chapter.split('\n')
    title = lines[0]
    content = '\n'.join(lines[1:])
    
    # Save each chapter separately
    with open(f"chapter_{i:02d}_{title.replace(' ', '_')}.md", "w") as f:
        f.write(f"# {title}\n\n{content}")
```

## Error Handling

```python theme={null}
from markitdown import MarkItDown
from markitdown._exceptions import (
    MissingDependencyException,
    UnsupportedFormatException,
    FileConversionException
)

md = MarkItDown()

try:
    result = md.convert("file.ext")
    print(result.markdown)
except MissingDependencyException as e:
    print(f"Missing dependency: {e}")
    print("Install with: pip install markitdown[all]")
except UnsupportedFormatException as e:
    print(f"Unsupported format: {e}")
except FileConversionException as e:
    print(f"Conversion failed: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

## Source Code Reference

```
packages/markitdown/src/markitdown/converters/
├── _csv_converter.py           # CSV tables
├── _plain_text_converter.py    # JSON, TXT, MD
├── _rss_converter.py           # XML/RSS/Atom
├── _zip_converter.py           # ZIP archives
├── _epub_converter.py          # EPUB books
└── _ipynb_converter.py         # Jupyter notebooks
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Format Overview" icon="list" href="/formats/overview">
    See all supported formats
  </Card>

  <Card title="Python API" icon="code" href="/api/python">
    Learn the programmatic interface
  </Card>
</CardGroup>