Metadata-Version: 2.4
Name: mkdocs-excel-plugin
Version: 1.0.0
Summary: MkDocs plugin for rendering Excel files as HTML tables
Author-email: Wangjunyu <wjyzc@foxmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/mkdocs-excel-plugin
Project-URL: Documentation, https://github.com/yourusername/mkdocs-excel-plugin
Project-URL: Repository, https://github.com/yourusername/mkdocs-excel-plugin.git
Project-URL: Issues, https://github.com/yourusername/mkdocs-excel-plugin/issues
Keywords: mkdocs,excel,plugin,documentation,tables
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs>=1.1
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: markupsafe>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# mkdocs-excel-plugin

[![Tests](https://github.com/Wangjunyu/mkdocs-excel-plugin/workflows/Tests/badge.svg)](https://github.com/Wangjunyu/mkdocs-excel-plugin/actions)
[![PyPI version](https://badge.fury.io/py/mkdocs-excel-plugin.svg)](https://badge.fury.io/py/mkdocs-excel-plugin)
[![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-excel-plugin.svg)](https://pypi.org/project/mkdocs-excel-plugin/)
[![License](https://img.shields.io/pypi/l/mkdocs-excel-plugin.svg)](https://github.com/Wangjunyu/mkdocs-excel-plugin/blob/main/LICENSE)

A MkDocs plugin that renders Excel files as beautiful HTML tables with complete style preservation.

## ✨ Features

- 🎨 **Complete Style Preservation**: Maintains Excel's background colors, fonts, borders, and alignment
- 📊 **Merged Cell Support**: Perfect handling of colspan and rowspan
- 🔄 **Multi-sheet Processing**: Render single sheets or all sheets at once
- ⚡ **Smart Caching**: Built-in caching for improved performance
- 🎯 **Size Control**: Configurable row/column limits for large files
- 🌓 **Theme Compatibility**: Works seamlessly with Material and other MkDocs themes
- 🛡️ **Error Handling**: Friendly error messages for missing files or sheets

## 🚀 Installation

```bash
pip install mkdocs-excel-plugin
```

## 📖 Quick Start

1. Add the plugin to your `mkdocs.yml`:

```yaml
plugins:
  - excel
```

2. Use Excel macros in your markdown:

```markdown
<!-- Render a single sheet -->
{{ render_excel_sheet('data.xlsx', 'Sheet1') }}

<!-- Render all sheets -->
{{ render_excel_all_sheets('data.xlsx') }}

<!-- List available sheets -->
{{ list_excel_sheets('data.xlsx') }}
```

## ⚙️ Configuration

```yaml
plugins:
  - excel:
      cache_enabled: true        # Enable smart caching
      max_file_size_mb: 5       # Maximum file size
      default_max_rows: 1000    # Default row limit
      default_max_cols: 50      # Default column limit
      theme: "material"         # Theme compatibility
```

## 📝 Usage Examples

### Basic Usage
```markdown
{{ render_excel_sheet('sales.xlsx', 'Q1 Data') }}
```

### Advanced Usage
```markdown
<!-- Limit table size -->
{{ render_excel_sheet('large.xlsx', 'Data', max_rows=100, max_cols=20) }}

<!-- Selective rendering -->
{{ render_excel_all_sheets('report.xlsx', include_sheets=['Summary', 'Details']) }}

<!-- Exclude specific sheets -->
{{ render_excel_all_sheets('report.xlsx', exclude_sheets=['Raw Data']) }}
```

## 🎯 Supported Features

- ✅ Background colors and gradients
- ✅ Font colors, bold, italic, sizes
- ✅ Text alignment (horizontal/vertical)
- ✅ Border styles and colors
- ✅ Merged cells with proper span
- ✅ Excel theme colors
- ✅ Multiple worksheets
- ✅ Relative file paths
- ✅ Performance warnings
- ✅ Comprehensive error handling

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and contribute to the project.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙋‍♂️ Support

If you encounter any issues or have questions, please file an issue on [GitHub](https://github.com/Wangjunyu/mkdocs-excel-plugin/issues).
