aspose-words-markitdown 0.1.3
Aspose.Words plugin for MarkItDown
Requires Python: >=3.13
Keywords: aspose, conversion, doc, epub, markdown, markitdown, mhtml, odt, pdf, plugin, rtf, word

# Aspose.Words for MarkItDown

![Python Version](https://img.shields.io/badge/python-3.12+-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## Overview
**Aspose.Words for MarkItDown** is a free plugin for [MarkItDown](https://github.com/microsoft/markitdown) based on [Aspose.Words for Python via .Net](https://products.aspose.com/words/python-net/) commercial library.  
The plugin is designed for parsing multiple document formats and converting them into Markdown suitable for AI processing.  
**Aspose.Words** plugin allows you to process new formats as `.doc`, `.rtf`, `.odt`, `.mhtml`, `.mobi` and `.azw3`.  
Moreover, you can get better conversion for `.docx`, `.pdf`, `.html`, `.epub` and `.txt` documents without your code modification.


## Features

- Convert `.docx`, `.pdf`, `.doc`, `.rtf`, `.html`, `.mhtml`, `.mobi`, `.azw3`, `.epub`, `.odt`, `.txt`, `.md` and `.xml` to Markdown.
- Support all document components, including paragraphs, tables, images, headers, and footers.
- Fully integrated with MarkItDown tool. You don't need to change your code to use the Aspose.Words plugin.

## Requirements

- [MarkItDown](https://github.com/microsoft/markitdown) version 0.1.0 or higher.
- [Aspose.Words for Python via .Net](https://products.aspose.com/words/python-net/). This library is a [commercial product](https://purchase.aspose.com/buy/words/python).  
You'll need to obtain a valid license for Aspose.Words. The package will install this dependency, but you're responsible for complying with Aspose's licensing terms.

## Installation

```bash
pip install aspose-words-markitdown
```

## Usage

### Make sure the plugin is installed correctly
List MarkItDown plugins with the command:
```
markitdown --list-plugins
```
Check the plugin is installed:
```
Installed MarkItDown 3rd-party Plugins:
  * aspose_words_markitdown  (package: aspose_words_markitdown)
```

### Command Line Interface

You can use the original `markitdown` CLI in the common way. Just add the `--use-plugins` option to enable the plugin.

#### Convert a Single File

```bash
markitdown test.doc -o out.md --use-plugins
```

### Python API

Basic usage in Python:

```python
from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True) # Set to True to enable the plugin
result = md.convert("test.doc")
print(result.text_content)
```


## Set License

### Environment Variables
To activate your Aspose.Words for Python license, set the corresponding environment variable.  
Refer to the OS-specific instructions below:

**Unix-based (Linux/macOS):**
```
export ASPOSE_WORDS_LICENSE_PATH="/path/to/license/aspose.words.lic"
```
**Windows-based:**
```
set ASPOSE_WORDS_LICENSE_PATH=c:\path\to\license\aspose.words.lic
```
**Python API:**
```
from aspose_words_markitdown import LicenseManager

LicenseManager().apply_license("/path/to/license/aspose.words.lic")
```

## Running Tests

To run unit tests for **Aspose.Words for MarkItDown**, follow these steps:

### 1. Navigate to the package directory

From the root of the repository, change into the package directory:

```bash
cd /packages/aspose-words-markitdown/tests
```

### 2. Install test dependencies

Make sure `pytest` is installed:

```bash
pip install pytest
```

### 3. Run tests using `pytest`

To run all tests:

```bash
pytest
```

## License

This package is licensed under the MIT License. However, it depends on Aspose.Words for Python via .Net library, which is proprietary, closed-source library.

⚠️ You must obtain valid license for Aspose.Words for Python via .Net library. This repository does not include or distribute any proprietary components.

## Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.