chore: restructure as installable PyPI package v1.0.0

tanhtm · tanhtm · commit f57fda0f6da7 · 2026-04-15T23:10:12.000+07:00
- Move logic into src/md2html_tailwind4/ (converter.py, cli.py, __init__.py)
- Add pyproject.toml with hatchling build backend and CLI entry point
- Update README with installation and usage instructions
- Add CHANGELOG.md
diff --git a/.gitignore b/.gitignore
@@ -205,3 +205,4 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+markdown2html_tailwind.py
diff --git a/.python-version b/.python-version
@@ -0,0 +1 @@
+3.11
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-04-15
+
+### Added
+
+- Initial release of `md2html-tailwind4`
+- `Converter` class with `convert_md_to_html()` method
+- Tailwind CSS 4 class annotations for all standard HTML elements (h1–h6, p, ul, ol, li, blockquote, img, pre, code, strong, em, a, hr)
+- Responsive table styling with overflow scrolling
+- Audio table support: 3-column tables with media URLs are converted to interactive audio player widgets
+- Django template delimiter escaping (`{{ }}`, `{% %}`, `{# #}`) inside code blocks
+- External links automatically get `target="_blank"` and `rel="noopener noreferrer"`
+- Dark mode support via Tailwind `dark:` variants
+- CLI entry point: `md2html input.md output.html`
+- `src/` layout for clean PyPI packaging with `hatchling` build backend
diff --git a/README.md b/README.md
@@ -1 +1,47 @@
-# md2html-tailwind4
+# md2html-tailwind4
+
+A Python package that converts Markdown to clean, styled HTML using **Tailwind CSS 4** classes.
+
+Designed for projects that render HTML inside a Tailwind-powered frontend (Django, FastAPI, static sites, etc.). No build step required — just pass in Markdown, get back ready-to-render HTML.
+
+## Features
+
+- Converts Markdown to HTML with full Tailwind CSS 4 class annotations
+- Responsive tables with overflow scrolling
+- Audio table support (3-column tables with media URLs become interactive audio players)
+- Automatically escapes Django template delimiters (`{{ }}`, `{% %}`) inside code blocks
+- External links get `target="_blank"` and `rel="noopener noreferrer"` automatically
+- Dark mode support via Tailwind's `dark:` variants
+- CLI tool included
+
+## Installation
+
+```bash
+pip install md2html-tailwind4
+```
+
+## Usage
+
+### Python API
+
+```python
+from md2html_tailwind4 import Converter
+
+converter = Converter()
+html = converter.convert_md_to_html("# Hello\n\nThis is **Markdown**.")
+print(html)
+```
+
+### Command Line
+
+```bash
+md2html input.md output.html
+```
+
+## Requirements
+
+- Python >= 3.11
+
+## License
+
+MIT — White Neuron Co., Ltd.
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "md2html-tailwind4"
+version = "1.0.0"
+description = "A Python package that converts Markdown to HTML using Tailwind CSS 4 for styling."
+authors = [
+    { name = "White Neuron Co., Ltd.", email = "contact@whiteneuron.com" },
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["markdown", "html", "tailwind", "tailwindcss", "converter"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: HTML",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = [
+    "beautifulsoup4>=4.14.3",
+    "markdown>=3.10.2",
+]
+
+[project.scripts]
+md2html = "md2html_tailwind4.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/md2html_tailwind4"]
diff --git a/src/md2html_tailwind4/__init__.py b/src/md2html_tailwind4/__init__.py
@@ -0,0 +1,3 @@
+from .converter import Converter
+
+__all__ = ["Converter"]
diff --git a/src/md2html_tailwind4/cli.py b/src/md2html_tailwind4/cli.py
@@ -0,0 +1,26 @@
+import argparse
+
+from .converter import Converter
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog='md2html',
+        description='Convert Markdown to HTML with Tailwind CSS 4 classes.',
+    )
+    parser.add_argument('input', help='Path to the input Markdown file')
+    parser.add_argument('output', help='Path to the output HTML file')
+    args = parser.parse_args()
+
+    with open(args.input, 'r', encoding='utf-8') as f:
+        markdown_content = f.read()
+
+    converter = Converter()
+    html_content = converter.convert_md_to_html(markdown_content)
+
+    with open(args.output, 'w', encoding='utf-8') as f:
+        f.write(html_content)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/src/md2html_tailwind4/converter.py b/src/md2html_tailwind4/converter.py
@@ -0,0 +1,208 @@
+import markdown
+import re
+from bs4 import BeautifulSoup
+
+
+class Converter:
+    def __init__(self):
+        pass
+
+    def convert_md_to_html(self, markdown_content):
+        # Convert Markdown to HTML with richer extensions for broader content support.
+        html_content = markdown.markdown(
+            markdown_content,
+            extensions=['tables', 'attr_list', 'fenced_code', 'sane_lists', 'nl2br'],
+        )
+
+        # Parse the HTML content and convert tables to custom divs
+        soup = BeautifulSoup(html_content, 'html.parser')
+
+        # Add Tailwind classes to various elements
+        self.add_tailwind_classes(soup)
+
+        # Convert tables to custom divs
+        self.convert_tables(soup)
+
+        # Escape Django template delimiters in code examples so they render literally.
+        self.escape_django_template_syntax_in_code_blocks(soup)
+
+        # Create the full HTML content with JavaScript for play/pause toggle
+        full_html_content = self.create_full_html(soup)
+
+        return full_html_content
+
+    def add_tailwind_classes(self, soup):
+        for h1 in soup.find_all('h1'):
+            h1['class'] = 'text-2xl sm:text-3xl lg:text-4xl font-bold tracking-tight mb-4 sm:mb-5 text-neutral-900 dark:text-neutral-100'
+
+        for h2 in soup.find_all('h2'):
+            h2['class'] = 'text-xl sm:text-2xl lg:text-3xl font-bold tracking-tight mt-8 mb-3 text-neutral-900 dark:text-neutral-100'
+
+        for h3 in soup.find_all('h3'):
+            h3['class'] = 'text-lg sm:text-xl lg:text-2xl font-semibold mt-6 mb-3 text-neutral-900 dark:text-neutral-100'
+
+        for h4 in soup.find_all('h4'):
+            h4['class'] = 'text-base sm:text-lg font-semibold mt-5 mb-2 text-neutral-800 dark:text-neutral-200'
+
+        for h5 in soup.find_all('h5'):
+            h5['class'] = 'text-base font-semibold mt-4 mb-2 text-neutral-800 dark:text-neutral-200'
+
+        for h6 in soup.find_all('h6'):
+            h6['class'] = 'text-sm font-semibold uppercase tracking-wide mt-4 mb-2 text-neutral-700 dark:text-neutral-300'
+
+        for p in soup.find_all('p'):
+            p['class'] = 'mb-4 text-base leading-7 text-pretty text-justify text-neutral-800 dark:text-neutral-200'
+
+        for ul in soup.find_all('ul'):
+            ul['class'] = 'list-disc list-outside pl-6 mb-4 space-y-1 text-base leading-7 text-justify text-neutral-800 dark:text-neutral-200'
+
+        for ol in soup.find_all('ol'):
+            ol['class'] = 'list-decimal list-outside pl-6 mb-4 space-y-1 text-base leading-7 text-justify text-neutral-800 dark:text-neutral-200'
+
+        for li in soup.find_all('li'):
+            li['class'] = 'leading-7'
+
+        for blockquote in soup.find_all('blockquote'):
+            blockquote['class'] = 'mb-5 p-4 sm:p-5 rounded-r-xl border-l-4 bg-neutral-100 text-neutral-700 border-neutral-400 italic text-base leading-7 quote dark:bg-neutral-900/60 dark:text-neutral-300 dark:border-neutral-600'
+
+        for img in soup.find_all('img'):
+            img['class'] = 'mx-auto my-5 w-full max-w-4xl h-auto rounded-xl border border-neutral-200 shadow-sm dark:border-neutral-700 dark:shadow-neutral-950/30'
+
+        for pre in soup.find_all('pre'):
+            pre['class'] = 'my-5 overflow-x-auto rounded-xl border border-neutral-200 bg-neutral-950 p-4 text-sm leading-6 text-neutral-100 dark:border-neutral-700 dark:bg-neutral-950 dark:text-neutral-100'
+
+        for code in soup.find_all('code'):
+            if code.parent and code.parent.name == 'pre':
+                code['class'] = 'bg-transparent p-0 text-inherit font-mono'
+            else:
+                code['class'] = 'px-1.5 py-0.5 rounded-md bg-neutral-100 text-[0.9em] font-mono text-neutral-900 dark:bg-neutral-800 dark:text-neutral-100'
+
+        for strong in soup.find_all('strong'):
+            strong['class'] = 'font-semibold text-neutral-900 dark:text-neutral-100'
+
+        for em in soup.find_all('em'):
+            em['class'] = 'italic text-neutral-700 dark:text-neutral-300'
+
+        for a in soup.find_all('a'):
+            a['class'] = 'text-sky-700 underline decoration-sky-300 underline-offset-2 hover:text-sky-900 transition-colors dark:text-sky-300 dark:decoration-sky-600 dark:hover:text-sky-200'
+            if a.get('href', '').startswith(('http://', 'https://')):
+                a['target'] = '_blank'
+                a['rel'] = 'noopener noreferrer'
+
+        for hr in soup.find_all('hr'):
+            hr['class'] = 'my-8 border-neutral-300 dark:border-neutral-700'
+
+    def convert_tables(self, soup):
+        for table in soup.find_all('table'):
+            rows = table.find_all('tr')
+            if len(rows) == 0:
+                continue
+
+            # Check if the first row is a header
+            first_row_cells = rows[0].find_all(['th', 'td'])
+            has_headers = len(first_row_cells) == 3 and all(th.name == 'th' for th in first_row_cells)
+
+            # Only convert dedicated audio tables; keep all other tables semantic/responsive.
+            if not has_headers or not self._is_audio_table(rows):
+                self._style_as_responsive_table(soup, table)
+                continue
+
+            start_index = 1 if has_headers else 0
+            divs = []
+
+            for row in rows[start_index:]:
+                cells = row.find_all(['td', 'th'])
+                if len(cells) >= 2:  # Ensure there are at least two cells per row
+                    div = soup.new_tag('div', **{'class': 'my-3 rounded-xl border border-neutral-200 bg-white p-3 sm:p-4 shadow-sm flex flex-col sm:flex-row sm:items-center sm:justify-center gap-2 sm:gap-3 dark:border-neutral-700 dark:bg-neutral-900 dark:shadow-neutral-950/30'})
+                    span1 = soup.new_tag('span', **{'class': 'font-semibold rounded-lg bg-neutral-800 px-3 py-2 text-white text-sm sm:text-base dark:bg-neutral-700'})
+                    span1.string = cells[0].get_text()
+                    span2 = soup.new_tag('span', **{'class': 'font-semibold rounded-lg bg-neutral-700 px-3 py-2 text-white text-sm sm:text-base break-words dark:bg-neutral-600'})
+                    span2_content = cells[1].get_text()
+                    span2.append(soup.new_string(span2_content))
+                    if len(cells) == 3 and cells[2].get_text().strip():
+                        audio_button = soup.new_tag('button', **{'class': 'audio-button ml-2', 'data-state': 'play'})
+                        audio_button.string = '▶️'
+                        audio_url = cells[2].get_text().strip()
+                        audio_id = span2_content.lower().replace(' ', '_').replace('[', '').replace(']', '')
+                        audio = soup.new_tag('audio', **{'src': audio_url, 'class': 'hidden', 'controls': ''})
+                        audio_button['onclick'] = f"togglePlayPause('{audio_id}', this);"
+                        audio['id'] = audio_id
+                        span2.append(audio_button)
+                        span2.append(audio)
+                    div.append(span1)
+                    div.append(span2)
+                    divs.append(div)
+            if divs:
+                table.replace_with(*divs)
+            else:
+                table.decompose()
+
+    @staticmethod
+    def _is_audio_table(rows):
+        # Audio-table mode is only valid when the 3rd column consistently contains media URLs.
+        media_suffixes = ('.mp3', '.wav', '.ogg', '.m4a', '.aac', '.webm')
+        data_rows = rows[1:] if len(rows) > 1 else []
+        if not data_rows:
+            return False
+
+        third_values = []
+        for row in data_rows:
+            cells = row.find_all(['td', 'th'])
+            if len(cells) < 3:
+                return False
+            third_values.append(cells[2].get_text().strip().lower())
+
+        if not all(third_values):
+            return False
+
+        return all(value.startswith(('http://', 'https://', '/')) or value.endswith(media_suffixes) for value in third_values)
+
+    def _style_as_responsive_table(self, soup, table):
+        table['class'] = 'min-w-full border-collapse text-sm sm:text-base'
+        table['style'] = 'color: var(--color-base-content); border-color: var(--color-base-300);'
+
+        thead = table.find('thead')
+        if thead:
+            thead['class'] = ''
+            thead['style'] = 'background-color: var(--color-base-300); color: var(--color-base-content);'
+        for th in table.find_all('th'):
+            th['class'] = 'border px-3 py-2 text-left font-semibold whitespace-nowrap'
+            th['style'] = 'border-color: var(--color-base-300); color: var(--color-base-content);'
+
+        for td in table.find_all('td'):
+            td['class'] = 'border px-3 py-2 align-top'
+            td['style'] = 'border-color: var(--color-base-300); color: var(--color-base-content);'
+
+        wrapper = soup.new_tag(
+            'div',
+            **{
+                'class': 'my-5 overflow-x-auto rounded-xl border shadow-sm',
+                'style': 'border-color: var(--color-base-300); background-color: var(--color-base-100); color: var(--color-base-content);',
+            },
+        )
+        table.wrap(wrapper)
+
+    def create_full_html(self, soup):
+        return str(soup)
+
+    def escape_django_template_syntax_in_code_blocks(self, soup):
+        for tag in soup.find_all(['code', 'pre']):
+            # Keep code samples readable while preventing Django template parsing.
+            if tag.string is not None:
+                tag.string.replace_with(self._escape_django_delimiters(str(tag.string)))
+                continue
+
+            for text_node in tag.find_all(string=True):
+                text_node.replace_with(self._escape_django_delimiters(str(text_node)))
+
+    @staticmethod
+    def _escape_django_delimiters(text):
+        token_map = {
+            '{{': '{% templatetag openvariable %}',
+            '}}': '{% templatetag closevariable %}',
+            '{%': '{% templatetag openblock %}',
+            '%}': '{% templatetag closeblock %}',
+            '{#': '{% templatetag opencomment %}',
+            '#}': '{% templatetag closecomment %}',
+        }
+        return re.sub(r'\{\{|\}\}|\{%|%\}|\{#|#\}', lambda m: token_map[m.group(0)], text)
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+from .converter import Converter`
	`2`	`+`
	`3`	`+__all__ = ["Converter"]`