md2indexhtml 0.2.1

Convert Markdown files to index.html for Odoo modules

md2indexhtml

md2indexhtml is a Python package designed to simplify the creation of index.html files for Odoo modules. It converts Markdown files to HTML with a clean, modern style that integrates well with Odoo's documentation system. The package supports both markdown content and direct HTML sections, allowing for flexible and beautiful documentation.

Features

• Automatically converts Markdown to styled HTML
• Creates index.html in the static/description directory (Odoo standard location)
• Supports direct HTML sections in markdown files
• Automatic image handling and migration
• Maintains image directory structure
• Converts markdown headers (#, ##) into styled sections automatically
• Creates responsive card-based layouts for content
• Applies modern, inline styling without external CSS
• Simple command-line interface
• Flexible output path options

Installation

Install the package using pip:

pip install md2indexhtml

Usage

Basic Usage

The simplest way to use md2indexhtml is to run it in your Odoo module directory:

cd your_odoo_module
md2indexhtml README.md

This will:

1. Convert your README.md to HTML
2. Create a static/description directory if it doesn't exist
3. Save the converted file as index.html in that directory

Without Arguments

If you run md2indexhtml without any arguments in a directory containing a markdown file:

cd your_odoo_module
md2indexhtml

It will automatically:

1. Find the first .md file in the current directory
2. Convert it to HTML
3. Save it as static/description/index.html

Custom Title

You can specify a custom title for the HTML document (defaults to "Documentation"):

md2indexhtml README.md --title "My Documentation"

Custom Output Path

You can specify a custom output path using the --output or -o argument:

md2indexhtml README.md --output /path/to/output/docs.html
# or use the short form
md2indexhtml README.md -o /path/to/output/docs.html

Mixing HTML and Markdown

You can mix direct HTML sections with markdown content in your files:

<section style="background: #003554;">
    <!-- Your custom HTML section -->
</section>

# Module Title
## Feature 1
- Feature description
- Another point

<section style="background: linear-gradient(...);">
    <!-- Another HTML section -->
</section>

Image Handling

The package automatically handles images in both Markdown and HTML formats:

# Using Markdown syntax
![Alt text](any/path/screenshot.png)

# Using HTML syntax
<img src="path/to/screenshot.png" alt="Alt text">

When converting your documentation:

• All local images are automatically copied to an images/ directory in the output path
• Only the filename is kept, discarding the original directory structure
• Image paths in the HTML are updated to point to images/filename.png
• External images (http/https URLs) remain unchanged
• Base64 encoded images are preserved as is
• Missing images generate warnings but don't stop the conversion

For example:

An image at screenshots/feature.png becomes images/feature.png in the output An image at assets/img/demo/screenshot.png becomes images/screenshot.png An external image https://example.com/image.jpg remains unchanged A base64 image data:image/png;base64,... remains unchanged

Python API

You can also use the package programmatically in your Python code:

from md2indexhtml import convert_md_to_html

# Convert specific file
convert_md_to_html("README.md")

# Convert with custom output path
convert_md_to_html("README.md", output_path="docs/output.html")

# Convert with custom title
convert_md_to_html("README.md", title="My Documentation")

# Or let it find a markdown file automatically
convert_md_to_html()

Output Style

The converted HTML file includes:

• Gradient backgrounds for main sections
• Card-based layout for subsections
• Modern typography with Inter font
• Responsive design for all screen sizes
• Syntax highlighting for code blocks
• Clean lists and blockquotes styling
• Mobile-friendly layout
• All styles are inline (no external CSS needed)

Markdown Conversion

• # headers become full-width gradient sections
• ## headers become card sections with white backgrounds
• Lists, code blocks, and other markdown elements get appropriate styling
• Custom HTML sections are preserved exactly as written

Sample Usages

• 
• 
• 

Use with Odoo

This package is specifically designed for Odoo module documentation. When you publish your module, the generated index.html in static/description will automatically be used as the module's documentation page on the Odoo Apps store.

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue on GitHub.

License

This project is licensed under the MIT License.

Author

Fasil (@fasilwdr)
Email: [e-mail]