# md2indexhtml
`md2indexhtml` is a powerful Python package that converts Markdown files to beautifully styled HTML pages specifically designed for Odoo modules. It uses comprehensive Odoo frontend styling classes from `web.assets_frontend.min.css` to create professional, responsive documentation that integrates seamlessly with Odoo's design system.
<div align="center">
<h2>Transform Your Documentation</h2>
<p>Create stunning, professional HTML documentation from Markdown with authentic Odoo styling</p>
</div>
<div align="center">
<img src="https://raw.githubusercontent.com/fasilwdr/md2indexhtml/refs/heads/main/img/sample_usage1.jpg" alt="Professional Odoo Documentation" width="800"/>
</div>
<div align="center">
<img src="https://raw.githubusercontent.com/fasilwdr/md2indexhtml/refs/heads/main/img/sample_usage2.jpg" alt="Responsive Design Example" width="800"/>
</div>
<div align="center">
<img src="https://raw.githubusercontent.com/fasilwdr/md2indexhtml/refs/heads/main/img/sample_usage3.jpg" alt="Clean Layout Example" width="800"/>
</div>
<div align="center">
<p>Simple command, beautiful results:</p>
<pre><code>md2indexhtml README.md</code></pre>
</div>
## Features
- **Comprehensive Odoo Styling**: Uses authentic Odoo frontend classes for consistent design
- **Dictionary-Based Configuration**: Flexible styling system using JSON configuration files
- **Semantic HTML5**: Generates clean, accessible HTML with proper semantic structure
- **Automatic Image Handling**: Processes and copies images with responsive styling
- **Custom Style Configurations**: Override default styling with custom JSON configurations
- **CLI Integration**: Simple command-line interface with powerful options
- **Responsive Design**: Mobile-friendly layouts with Odoo's responsive classes
- **Typography Excellence**: Beautiful typography using Odoo's font system
- **Card-Based Layouts**: Automatic section organization into elegant card layouts
- **Table Enhancement**: Professional table styling with striped rows and hover effects
## Installation
Install the package using pip:
```bash
pip install md2indexhtml
```
## Quick Start
### Basic Usage
Convert your README.md to Odoo-styled HTML:
```bash
cd your_odoo_module
md2indexhtml README.md
```
This creates a beautifully styled `static/description/index.html` file perfect for the Odoo Apps Store.
### Without Arguments
If you have a markdown file in your current directory:
```bash
md2indexhtml
```
It automatically finds and converts the first `.md` file found.
## Advanced Usage
### Custom Output Path
Specify where to save the HTML file:
```bash
md2indexhtml README.md --output /path/to/docs.html
# or use the short form
md2indexhtml README.md -o /path/to/docs.html
```
### Custom Title
Set a custom title for your HTML document:
```bash
md2indexhtml README.md --title "Module Documentation"
```
### Custom Style Configuration
Create a JSON file with your custom styling preferences:
```json
{
"h1": {
"class": "display-2 text-primary text-center mb-5",
"style": "border-bottom: 3px solid #875A7B;"
},
"p": {
"class": "lead text-muted mb-4"
},
"table": {
"class": "table table-dark table-striped table-hover"
}
}
```
Then apply it:
```bash
md2indexhtml README.md --style-config my-styles.json
```
### View Default Configuration
See all available styling options:
```bash
md2indexhtml --show-config
```
This displays the complete default Odoo styling configuration organized by categories.
## Configuration System
### Default Odoo Styling
The package comes with comprehensive default styling that covers:
- **Typography**: Headers (h1-h6), paragraphs, emphasis, code blocks
- **Lists**: Unordered, ordered, and definition lists
- **Tables**: Full table styling with headers, borders, and hover effects
- **Forms**: Input fields, buttons, fieldsets with Odoo styling
- **Layout**: Containers, sections, cards, and grid systems
- **Media**: Images, figures, and responsive media elements
- **Navigation**: Navigation bars, breadcrumbs, and links
- **Interactive**: Alerts, badges, progress bars, and tooltips
### Custom Configuration Format
Style configurations use a simple dictionary format:
```python
{
"element_name": {
"attribute_name": "attribute_value",
"class": "css-classes",
"id": "element-id",
"style": "inline-css"
}
}
```
**Examples:**
```json
{
"h2": {
"class": "text-center text-primary mb-4",
"style": "border-bottom: 2px solid #875A7B;"
},
"blockquote": {
"class": "alert alert-info border-left-primary",
"style": "border-left: 4px solid #17a2b8;"
},
"img": {
"class": "img-fluid rounded shadow-lg mb-4 d-block mx-auto",
"style": "max-height: 400px;"
}
}
```
### Styling Categories
The default configuration includes styling for:
1. **Typography Elements**: h1-h6, p, strong, em, small, mark
2. **List Elements**: ul, ol, li, dl, dt, dd
3. **Table Elements**: table, thead, tbody, tr, th, td
4. **Code Elements**: pre, code
5. **Media Elements**: img, figure, figcaption
6. **Layout Elements**: div, section, article, main, aside, header, footer
7. **Form Elements**: form, input, textarea, select, button, fieldset, legend
8. **Interactive Elements**: a, nav, details, summary
## Content Structure
### Markdown Conversion
The package intelligently converts markdown elements:
- `# Headers` become full-width sections with Odoo styling
- `## Subheaders` become card-based feature sections
- Lists are styled with Odoo's list classes
- Code blocks get syntax highlighting and proper spacing
- Images are automatically made responsive and centered
- Tables receive full Odoo table styling
### HTML Preservation
You can mix HTML directly in your markdown:
```markdown
# My Module
<section class="py-5 bg-primary text-white text-center">
<h2>Custom HTML Section</h2>
<p>This will be preserved exactly as written</p>
</section>
## Features
- Feature 1
- Feature 2
<div class="alert alert-warning">
<strong>Note:</strong> Important information here
</div>
```
### Image Handling
The package automatically processes images:
```markdown
# Using Markdown
# Using HTML
<img src="assets/demo.jpg" alt="Demo" />
```
**Automatic Processing:**
- Copies images to `images/` directory in output location
- Updates paths to use only filenames (flattens directory structure)
- Adds responsive classes automatically
- Preserves external URLs and base64 images
- Warns about missing images but continues processing
## Python API
Use the package programmatically:
```python
from md2indexhtml import convert_md_to_html
# Basic conversion
convert_md_to_html("README.md")
# With custom configuration
style_config = {
"h1": {"class": "display-1 text-center text-primary"},
"p": {"class": "lead mb-4"}
}
convert_md_to_html(
md_file_path="README.md",
title="My Documentation",
output_path="docs/index.html",
style_config=style_config
)
# Load configuration from file
from md2indexhtml.converter import create_style_config_from_file
config = create_style_config_from_file("styles.json")
convert_md_to_html("README.md", style_config=config)
```
## Output Features
The generated HTML includes:
- **Semantic Structure**: Proper HTML5 semantic elements
- **Responsive Design**: Mobile-first responsive layout
- **Odoo Integration**: Native Odoo styling classes
- **Typography**: Professional typography with Odoo fonts
- **Accessibility**: ARIA labels and semantic markup
- **Performance**: Optimized CSS and clean HTML structure
### Odoo Apps Store Ready
Files generated with `md2indexhtml` are specifically designed for the Odoo Apps Store:
- Uses `oe_structure` containers for proper Odoo integration
- Includes proper meta tags and viewport settings
- Follows Odoo's design guidelines and color schemes
- Optimized for the Apps Store's rendering system
## CLI Reference
```bash
# Convert with defaults
md2indexhtml README.md
# Custom title and output
md2indexhtml README.md --title "My Module" --output custom.html
# Apply custom styling
md2indexhtml README.md --style-config custom-styles.json
# View default configuration
md2indexhtml --show-config
# Get version
md2indexhtml --version
```
## Examples
### Basic Module Documentation
```markdown
# Inventory Management Pro
Advanced inventory management for Odoo with real-time tracking.
## Key Features
- Real-time stock tracking
- Automated reorder points
- Advanced reporting dashboard
- Mobile-friendly interface
## Installation
1. Download the module
2. Install in your Odoo instance
3. Configure your settings
## Screenshots
```
### Custom Styling Example
Create `custom-style.json`:
```json
{
"h1": {
"class": "display-3 text-center text-primary mb-5",
"style": "text-shadow: 2px 2px 4px rgba(0,0,0,0.1);"
},
"h2": {
"class": "h3 text-secondary mb-3 border-bottom border-primary pb-2"
},
"img": {
"class": "img-fluid rounded-lg shadow-lg mb-4 d-block mx-auto",
"style": "border: 3px solid #875A7B;"
}
}
```
Apply it:
```bash
md2indexhtml README.md --style-config custom-style.json
```
## Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues on GitHub.
### Development Setup
```bash
git clone https://github.com/fasilwdr/md2indexhtml.git
cd md2indexhtml
pip install -e .
```
## License
This project is licensed under the MIT License. See the LICENSE file for details.
## Author
**Fasil** (@fasilwdr)
Email: fasilwdr@hotmail.com
GitHub: https://github.com/fasilwdr
---
**Transform your Markdown documentation into professional, Odoo-ready HTML with md2indexhtml!**
Raw data
{
"_id": null,
"home_page": "https://github.com/fasilwdr/md2indexhtml",
"name": "md2indexhtml",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "markdown, html, odoo, documentation, frontend, styling, web, converter",
"author": "Fasil",
"author_email": "Fasil <fasilwdr@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7d/09/d93385b99d28c77549516cf1773964f38caa0cfe9e5386596b466ae3b831/md2indexhtml-0.5.0.tar.gz",
"platform": null,
"description": "# md2indexhtml\n\n`md2indexhtml` is a powerful Python package that converts Markdown files to beautifully styled HTML pages specifically designed for Odoo modules. It uses comprehensive Odoo frontend styling classes from `web.assets_frontend.min.css` to create professional, responsive documentation that integrates seamlessly with Odoo's design system.\n\n<div align=\"center\">\n <h2>Transform Your Documentation</h2>\n <p>Create stunning, professional HTML documentation from Markdown with authentic Odoo styling</p>\n</div>\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/fasilwdr/md2indexhtml/refs/heads/main/img/sample_usage1.jpg\" alt=\"Professional Odoo Documentation\" width=\"800\"/>\n</div>\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/fasilwdr/md2indexhtml/refs/heads/main/img/sample_usage2.jpg\" alt=\"Responsive Design Example\" width=\"800\"/>\n</div>\n\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/fasilwdr/md2indexhtml/refs/heads/main/img/sample_usage3.jpg\" alt=\"Clean Layout Example\" width=\"800\"/>\n</div>\n\n<div align=\"center\">\n <p>Simple command, beautiful results:</p>\n <pre><code>md2indexhtml README.md</code></pre>\n</div>\n\n## Features\n\n- **Comprehensive Odoo Styling**: Uses authentic Odoo frontend classes for consistent design\n- **Dictionary-Based Configuration**: Flexible styling system using JSON configuration files\n- **Semantic HTML5**: Generates clean, accessible HTML with proper semantic structure\n- **Automatic Image Handling**: Processes and copies images with responsive styling\n- **Custom Style Configurations**: Override default styling with custom JSON configurations\n- **CLI Integration**: Simple command-line interface with powerful options\n- **Responsive Design**: Mobile-friendly layouts with Odoo's responsive classes\n- **Typography Excellence**: Beautiful typography using Odoo's font system\n- **Card-Based Layouts**: Automatic section organization into elegant card layouts\n- **Table Enhancement**: Professional table styling with striped rows and hover effects\n\n## Installation\n\nInstall the package using pip:\n\n```bash\npip install md2indexhtml\n```\n\n## Quick Start\n\n### Basic Usage\n\nConvert your README.md to Odoo-styled HTML:\n\n```bash\ncd your_odoo_module\nmd2indexhtml README.md\n```\n\nThis creates a beautifully styled `static/description/index.html` file perfect for the Odoo Apps Store.\n\n### Without Arguments\n\nIf you have a markdown file in your current directory:\n\n```bash\nmd2indexhtml\n```\n\nIt automatically finds and converts the first `.md` file found.\n\n## Advanced Usage\n\n### Custom Output Path\n\nSpecify where to save the HTML file:\n\n```bash\nmd2indexhtml README.md --output /path/to/docs.html\n# or use the short form\nmd2indexhtml README.md -o /path/to/docs.html\n```\n\n### Custom Title\n\nSet a custom title for your HTML document:\n\n```bash\nmd2indexhtml README.md --title \"Module Documentation\"\n```\n\n### Custom Style Configuration\n\nCreate a JSON file with your custom styling preferences:\n\n```json\n{\n \"h1\": {\n \"class\": \"display-2 text-primary text-center mb-5\",\n \"style\": \"border-bottom: 3px solid #875A7B;\"\n },\n \"p\": {\n \"class\": \"lead text-muted mb-4\"\n },\n \"table\": {\n \"class\": \"table table-dark table-striped table-hover\"\n }\n}\n```\n\nThen apply it:\n\n```bash\nmd2indexhtml README.md --style-config my-styles.json\n```\n\n### View Default Configuration\n\nSee all available styling options:\n\n```bash\nmd2indexhtml --show-config\n```\n\nThis displays the complete default Odoo styling configuration organized by categories.\n\n## Configuration System\n\n### Default Odoo Styling\n\nThe package comes with comprehensive default styling that covers:\n\n- **Typography**: Headers (h1-h6), paragraphs, emphasis, code blocks\n- **Lists**: Unordered, ordered, and definition lists\n- **Tables**: Full table styling with headers, borders, and hover effects\n- **Forms**: Input fields, buttons, fieldsets with Odoo styling\n- **Layout**: Containers, sections, cards, and grid systems\n- **Media**: Images, figures, and responsive media elements\n- **Navigation**: Navigation bars, breadcrumbs, and links\n- **Interactive**: Alerts, badges, progress bars, and tooltips\n\n### Custom Configuration Format\n\nStyle configurations use a simple dictionary format:\n\n```python\n{\n \"element_name\": {\n \"attribute_name\": \"attribute_value\",\n \"class\": \"css-classes\",\n \"id\": \"element-id\",\n \"style\": \"inline-css\"\n }\n}\n```\n\n**Examples:**\n\n```json\n{\n \"h2\": {\n \"class\": \"text-center text-primary mb-4\",\n \"style\": \"border-bottom: 2px solid #875A7B;\"\n },\n \"blockquote\": {\n \"class\": \"alert alert-info border-left-primary\",\n \"style\": \"border-left: 4px solid #17a2b8;\"\n },\n \"img\": {\n \"class\": \"img-fluid rounded shadow-lg mb-4 d-block mx-auto\",\n \"style\": \"max-height: 400px;\"\n }\n}\n```\n\n### Styling Categories\n\nThe default configuration includes styling for:\n\n1. **Typography Elements**: h1-h6, p, strong, em, small, mark\n2. **List Elements**: ul, ol, li, dl, dt, dd\n3. **Table Elements**: table, thead, tbody, tr, th, td\n4. **Code Elements**: pre, code\n5. **Media Elements**: img, figure, figcaption\n6. **Layout Elements**: div, section, article, main, aside, header, footer\n7. **Form Elements**: form, input, textarea, select, button, fieldset, legend\n8. **Interactive Elements**: a, nav, details, summary\n\n## Content Structure\n\n### Markdown Conversion\n\nThe package intelligently converts markdown elements:\n\n- `# Headers` become full-width sections with Odoo styling\n- `## Subheaders` become card-based feature sections\n- Lists are styled with Odoo's list classes\n- Code blocks get syntax highlighting and proper spacing\n- Images are automatically made responsive and centered\n- Tables receive full Odoo table styling\n\n### HTML Preservation\n\nYou can mix HTML directly in your markdown:\n\n```markdown\n# My Module\n\n<section class=\"py-5 bg-primary text-white text-center\">\n <h2>Custom HTML Section</h2>\n <p>This will be preserved exactly as written</p>\n</section>\n\n## Features\n\n- Feature 1\n- Feature 2\n\n<div class=\"alert alert-warning\">\n <strong>Note:</strong> Important information here\n</div>\n```\n\n### Image Handling\n\nThe package automatically processes images:\n\n```markdown\n# Using Markdown\n\n\n# Using HTML\n<img src=\"assets/demo.jpg\" alt=\"Demo\" />\n```\n\n**Automatic Processing:**\n- Copies images to `images/` directory in output location\n- Updates paths to use only filenames (flattens directory structure)\n- Adds responsive classes automatically\n- Preserves external URLs and base64 images\n- Warns about missing images but continues processing\n\n## Python API\n\nUse the package programmatically:\n\n```python\nfrom md2indexhtml import convert_md_to_html\n\n# Basic conversion\nconvert_md_to_html(\"README.md\")\n\n# With custom configuration\nstyle_config = {\n \"h1\": {\"class\": \"display-1 text-center text-primary\"},\n \"p\": {\"class\": \"lead mb-4\"}\n}\n\nconvert_md_to_html(\n md_file_path=\"README.md\",\n title=\"My Documentation\",\n output_path=\"docs/index.html\",\n style_config=style_config\n)\n\n# Load configuration from file\nfrom md2indexhtml.converter import create_style_config_from_file\n\nconfig = create_style_config_from_file(\"styles.json\")\nconvert_md_to_html(\"README.md\", style_config=config)\n```\n\n## Output Features\n\nThe generated HTML includes:\n\n- **Semantic Structure**: Proper HTML5 semantic elements\n- **Responsive Design**: Mobile-first responsive layout\n- **Odoo Integration**: Native Odoo styling classes\n- **Typography**: Professional typography with Odoo fonts\n- **Accessibility**: ARIA labels and semantic markup\n- **Performance**: Optimized CSS and clean HTML structure\n\n### Odoo Apps Store Ready\n\nFiles generated with `md2indexhtml` are specifically designed for the Odoo Apps Store:\n\n- Uses `oe_structure` containers for proper Odoo integration\n- Includes proper meta tags and viewport settings\n- Follows Odoo's design guidelines and color schemes\n- Optimized for the Apps Store's rendering system\n\n## CLI Reference\n\n```bash\n# Convert with defaults\nmd2indexhtml README.md\n\n# Custom title and output\nmd2indexhtml README.md --title \"My Module\" --output custom.html\n\n# Apply custom styling\nmd2indexhtml README.md --style-config custom-styles.json\n\n# View default configuration\nmd2indexhtml --show-config\n\n# Get version\nmd2indexhtml --version\n```\n\n## Examples\n\n### Basic Module Documentation\n\n```markdown\n# Inventory Management Pro\n\nAdvanced inventory management for Odoo with real-time tracking.\n\n## Key Features\n\n- Real-time stock tracking\n- Automated reorder points\n- Advanced reporting dashboard\n- Mobile-friendly interface\n\n## Installation\n\n1. Download the module\n2. Install in your Odoo instance\n3. Configure your settings\n\n## Screenshots\n\n\n\n```\n\n### Custom Styling Example\n\nCreate `custom-style.json`:\n\n```json\n{\n \"h1\": {\n \"class\": \"display-3 text-center text-primary mb-5\",\n \"style\": \"text-shadow: 2px 2px 4px rgba(0,0,0,0.1);\"\n },\n \"h2\": {\n \"class\": \"h3 text-secondary mb-3 border-bottom border-primary pb-2\"\n },\n \"img\": {\n \"class\": \"img-fluid rounded-lg shadow-lg mb-4 d-block mx-auto\",\n \"style\": \"border: 3px solid #875A7B;\"\n }\n}\n```\n\nApply it:\n\n```bash\nmd2indexhtml README.md --style-config custom-style.json\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues on GitHub.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/fasilwdr/md2indexhtml.git\ncd md2indexhtml\npip install -e .\n```\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n## Author\n\n**Fasil** (@fasilwdr) \nEmail: fasilwdr@hotmail.com \nGitHub: https://github.com/fasilwdr\n\n---\n\n**Transform your Markdown documentation into professional, Odoo-ready HTML with md2indexhtml!**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Beautiful Markdown to HTML converter with comprehensive Odoo frontend styling",
"version": "0.5.0",
"project_urls": {
"Bug Reports": "https://github.com/fasilwdr/md2indexhtml/issues",
"Homepage": "https://github.com/fasilwdr/md2indexhtml",
"Source": "https://github.com/fasilwdr/md2indexhtml"
},
"split_keywords": [
"markdown",
" html",
" odoo",
" documentation",
" frontend",
" styling",
" web",
" converter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "abcef29cad5cfe30c3b7e913e8807f6508f31fe7fc1451c87d06effc76eb9e28",
"md5": "a81a7017f2b7933dae12c195f85208cd",
"sha256": "c25ff0127cad744a627064a497f4355f91524d133e9f8ab42289a58eab523a74"
},
"downloads": -1,
"filename": "md2indexhtml-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a81a7017f2b7933dae12c195f85208cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 14665,
"upload_time": "2025-07-08T21:15:04",
"upload_time_iso_8601": "2025-07-08T21:15:04.467013Z",
"url": "https://files.pythonhosted.org/packages/ab/ce/f29cad5cfe30c3b7e913e8807f6508f31fe7fc1451c87d06effc76eb9e28/md2indexhtml-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d09d93385b99d28c77549516cf1773964f38caa0cfe9e5386596b466ae3b831",
"md5": "97e9e31da417605f328ce320a9de0f31",
"sha256": "1fc9e6838370d5aca69f2d5bb8d575873fce2ec32f606a73d37028fa0d191a34"
},
"downloads": -1,
"filename": "md2indexhtml-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "97e9e31da417605f328ce320a9de0f31",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 17118,
"upload_time": "2025-07-08T21:15:05",
"upload_time_iso_8601": "2025-07-08T21:15:05.863607Z",
"url": "https://files.pythonhosted.org/packages/7d/09/d93385b99d28c77549516cf1773964f38caa0cfe9e5386596b466ae3b831/md2indexhtml-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 21:15:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fasilwdr",
"github_project": "md2indexhtml",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "md2indexhtml"
}
JSON
