mkdocs-excel-plugin

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

pip install mkdocs-excel-plugin

📖 Quick Start

1. Add the plugin to your mkdocs.yml:

plugins:
  - excel

2. Use Excel macros in your 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

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

{{ render_excel_sheet('sales.xlsx', 'Q1 Data') }}

Advanced Usage

<!-- 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 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 file for details.

🙋‍♂️ Support

If you encounter any issues or have questions, please file an issue on GitHub.