Markdown to HTML Converter (python, written by Claude Code)

Claude Code wrote this python project from the task below. It installed and ran on a clean Ubuntu 22.04 machine as written.

Task given to the agent:

TASK: Markdown to HTML Converter

Write a program that converts Markdown documents to HTML with support for GitHub Flavored Markdown extensions, syntax highlighting of code blocks, table of contents generation, and custom CSS styling.

FUNCTIONAL REQUIREMENTS:
- Accept a Markdown file path as a command-line argument
- Support standard Markdown: headings (h1-h6), bold, italic, strikethrough, links, images, blockquotes, ordered and unordered lists, horizontal rules, inline code, and code blocks
- Support GitHub Flavored Markdown extensions: tables, task lists (checkboxes), fenced code blocks with language identifiers, autolinks, and footnotes
- Apply syntax highlighting to fenced code blocks based on the specified language (support at least: python, javascript, java, c++, html, css, json, bash)
- Generate a table of contents from headings via --toc flag, inserted at the top of the document with anchor links
- Support custom CSS styling via --css flag (path to a CSS file to embed or link in the output)
- Support wrapping the output in a complete HTML document (with DOCTYPE, head, body) via --full-page flag, or outputting just the HTML fragment (default)
- Support automatic heading ID generation for anchor links based on heading text
- Support converting multiple Markdown files via --batch flag, with optional --index flag to generate an index page linking all converted files
- Print the HTML output to console by default
- Save the HTML to a file via --output flag (default: same base name with .html extension)
- If no input file is given, generate a sample Markdown document demonstrating all supported features (headings, lists, code blocks, tables, images, links, task lists, footnotes), convert it, and save both the Markdown source and HTML output
- Handle errors: invalid Markdown syntax (graceful degradation), missing linked files, and encoding issues

Create a complete Python project for a clean Ubuntu 22.04 machine with only Python 3.10+ installed. Include:
- Source code
- requirements.txt with all dependencies (direct and transitive) pinned to exact versions
- README.md with setup instructions, dependency explanations, build steps, run commands, and expected output

[]

"""
Markdown to HTML Converter

Converts Markdown files to HTML with GFM extensions, syntax highlighting,
table of contents generation, and custom CSS support.

Dependencies:
    - markdown (3.5.2)
    - Pygments (2.17.2)
"""

import argparse
import os
import re
import sys
from typing import Optional

import markdown
from markdown.extensions.toc import TocExtension
from markdown.extensions.codehilite import CodeHiliteExtension
from markdown.extensions.tables import TableExtension
from markdown.extensions.fenced_code import FencedCodeExtension
from pygments.formatters import HtmlFormatter


DEFAULT_CSS = """
body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
    line-height: 1.6;
    max-width: 900px;
    margin: 0 auto;
    padding: 2rem;
    color: #333;
    background-color: #fff;
}

h1, h2, h3, h4, h5, h6 {
    margin-top: 1.5em;
    margin-bottom: 0.5em;
    font-weight: 600;
    line-height: 1.25;
}

h1 { font-size: 2em; border-bottom: 1px solid #eaecef; padding-bottom: 0.3em; }
h2 { font-size: 1.5em; border-bottom: 1px solid #eaecef; padding-bottom: 0.3em; }
h3 { font-size: 1.25em; }

a { color: #0366d6; text-decoration: none; }
a:hover { text-decoration: underline; }

code {
    background-color: #f6f8fa;
    border-radius: 3px;
    padding: 0.2em 0.4em;
    font-size: 85%;
    font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
}

pre {
    background-color: #f6f8fa;
    border-radius: 6px;
    padding: 16px;
    overflow: auto;
    line-height: 1.45;
}

pre code {
    background-color: transparent;
    padding: 0;
}

blockquote {
    margin: 0;
    padding: 0 1em;
    color: #6a737d;
    border-left: 0.25em solid #dfe2e5;
}

table {
    border-collapse: collapse;
    width: 100%;
    margin-bottom: 1em;
}

th, td {
    border: 1px solid #dfe2e5;
    padding: 6px 13px;
}

th {
    background-color: #f6f8fa;
    font-weight: 600;
}

tr:nth-child(2n) { background-color: #f6f8fa; }

img { max-width: 100%; }

.toc {
    background-color: #f6f8fa;
    border: 1px solid #dfe2e5;
    border-radius: 6px;
    padding: 1em 1.5em;
    margin-bottom: 2em;
}

.toc ul { list-style-type: none; padding-left: 1.5em; }
.toc > ul { padding-left: 0; }
.toc li { margin: 0.3em 0; }

hr {
    height: 0.25em;
    padding: 0;
    margin: 24px 0;
    background-color: #e1e4e8;
    border: 0;
}

ul, ol { padding-left: 2em; }
li + li { margin-top: 0.25em; }
"""


class MarkdownToHtmlConverter:
    """Converts Markdown content to HTML with various enhancements."""

    def __init__(
        self,
        custom_css: Optional[str] = None,
        enable_toc: bool = True,
        enable_syntax_highlight: bool = True,
        toc_title: str = "Table of Contents",
        highlight_style: str = "github-dark",
    ):
        """
        Initialize the converter.

        Args:
            custom_css: Optional custom CSS string to use instead of default.
            enable_toc: Whether to generate a table of contents.
            enable_syntax_highlight: Whether to enable syntax highlighting.
            toc_title: Title for the table of contents section.
            highlight_style: Pygments style name for syntax highlighting.
        """
        self.custom_css = custom_css
        self.enable_toc = enable_toc
        self.enable_syntax_highlight = enable_syntax_highlight
        self.toc_title = toc_title
        self.highlight_style = highlight_style

    def _build_extensions(self) -> list:
        """Build the list of Markdown extensions to use."""
        extensions = [
            "markdown.extensions.tables",
            "markdown.extensions.fenced_code",
            "markdown.extensions.footnotes",
            "markdown.extensions.attr_list",
            "markdown.extensions.def_list",
            "markdown.extensions.abbr",
            "markdown.extensions.md_in_html",
            "markdown.extensions.sane_lists",
            "markdown.extensions.smarty",
            "markdown.extensions.nl2br",
        ]

        if self.enable_toc:
            extensions.append(TocExtension(
                title=self.toc_title,
                permalink=True,
                permalink_title="Link to this section",
                toc_depth="2-4",
            ))

        if self.enable_syntax_highlight:
            extensions.append(CodeHiliteExtension(
                linenums=False,
                css_class="highlight",
                pygments_style=self.highlight_style,
                guess_lang=True,
            ))

        return extensions

    def _get_css(self) -> str:
        """Get the CSS to embed in the HTML output."""
        css = self.custom_css if self.custom_css else DEFAULT_CSS

        if self.enable_syntax_highlight:
            formatter = HtmlFormatter(style=self.highlight_style)
            highlight_css = formatter.get_style_defs(".highlight")
            css += f"\n/* Syntax Highlighting */\n{highlight_css}\n"

        return css

    def convert(self, markdown_text: str) -> str:
        """
        Convert Markdown text to a complete HTML document.

        Args:
            markdown_text: The Markdown source text.

        Returns:
            A complete HTML document string.
        """
        extensions = self._build_extensions()
        md = markdown.Markdown(extensions=extensions)
        html_body = md.convert(markdown_text)

        toc_html = ""
        if self.enable_toc and hasattr(md, "toc") and md.toc:
            toc_content = md.toc
            if toc_content.strip() and "<li>" in toc_content:
                toc_html = f'<div class="toc">\n{toc_content}\n</div>\n'

        css = self._get_css()

        title = self._extract_title(markdown_text)

        html_document = f"""<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{title}</title>
    <style>
{css}
    </style>
</head>
<body>
{toc_html}{html_body}
</body>
</html>"""

        return html_document

    def convert_file(self, input_path: str, output_path: Optional[str] = None) -> str:
        """
        Convert a Markdown file to an HTML file.

        Args:
            input_path: Path to the input Markdown file.
            output_path: Path for the output HTML file. If None, uses the
                         same name with .html extension.

        Returns:
            The path to the generated HTML file.
        """
        if not os.path.exists(input_path):
            raise FileNotFoundError(f"Input file not found: {input_path}")

        with open(input_path, "r", encoding="utf-8") as f:
            markdown_text = f.read()

        html = self.convert(markdown_text)

        if output_path is None:
            base, _ = os.path.splitext(input_path)
            output_path = base + ".html"

        os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)

        with open(output_path, "w", encoding="utf-8") as f:
            f.write(html)

        return output_path

    @staticmethod
    def _extract_title(markdown_text: str) -> str:
        """Extract the first heading from Markdown text as a title."""
        for line in markdown_text.split("\n"):
            line = line.strip()
            match = re.match(r"^#+\s+(.+)$", line)
            if match:
                return match.group(1)
        return "Converted Document"


def load_css_file(css_path: str) -> str:
    """Load a CSS file and return its contents."""
    with open(css_path, "r", encoding="utf-8") as f:
        return f.read()


def main():
    """Main entry point for the CLI."""
    parser = argparse.ArgumentParser(
        description="Convert Markdown files to HTML with GFM extensions, "
                    "syntax highlighting, and table of contents."
    )
    parser.add_argument("input", help="Input Markdown file path")
    parser.add_argument(
        "-o", "--output",
        help="Output HTML file path (default: same name with .html extension)"
    )
    parser.add_argument(
        "--css",
        help="Path to a custom CSS file"
    )
    parser.add_argument(
        "--no-toc",
        action="store_true",
        help="Disable table of contents generation"
    )
    parser.add_argument(
        "--no-highlight",
        action="store_true",
        help="Disable syntax highlighting"
    )
    parser.add_argument(
        "--toc-title",
        default="Table of Contents",
        help="Title for the table of contents (default: 'Table of Contents')"
    )
    parser.add_argument(
        "--highlight-style",
        default="github-dark",
        help="Pygments style for syntax highlighting (default: 'github-dark')"
    )
    parser.add_argument(
        "--stdout",
        action="store_true",
        help="Print HTML to stdout instead of writing to a file"
    )

    args = parser.parse_args()

    custom_css = None
    if args.css:
        try:
            custom_css = load_css_file(args.css)
        except FileNotFoundError:
            print(f"Error: CSS file not found: {args.css}", file=sys.stderr)
            sys.exit(1)

    converter = MarkdownToHtmlConverter(
        custom_css=custom_css,
        enable_toc=not args.no_toc,
        enable_syntax_highlight=not args.no_highlight,
        toc_title=args.toc_title,
        highlight_style=args.highlight_style,
    )

    try:
        if args.stdout:
            with open(args.input, "r", encoding="utf-8") as f:
                markdown_text = f.read()
            html = converter.convert(markdown_text)
            print(html)
        else:
            output_path = converter.convert_file(args.input, args.output)
            print(f"HTML written to: {output_path}")
    except FileNotFoundError as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Error during conversion: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

# Markdown to HTML Converter

A Python-based Markdown to HTML converter with GFM extensions, syntax highlighting, table of contents generation, and custom CSS support.

## Dependencies

- **markdown** (3.5.2) - Python Markdown parser with extension support
- **Pygments** (2.17.2) - Syntax highlighting engine

## Installation

```bash
pip install -r requirements.txt
```

## Usage

### Command Line

```bash
# Basic conversion
python converter.py input.md

# Specify output file
python converter.py input.md -o output.html

# Use custom CSS
python converter.py input.md --css custom.css

# Disable table of contents
python converter.py input.md --no-toc

# Disable syntax highlighting
python converter.py input.md --no-highlight

# Change highlight style
python converter.py input.md --highlight-style monokai

# Print to stdout
python converter.py input.md --stdout
```

### As a Library

```python
from converter import MarkdownToHtmlConverter

converter = MarkdownToHtmlConverter(
    enable_toc=True,
    enable_syntax_highlight=True,
    highlight_style="github-dark",
)

markdown_text = "# Hello\n\nThis is **bold** text."
html = converter.convert(markdown_text)

# Or convert a file
converter.convert_file("input.md", "output.html")
```

## Features

- GFM (GitHub Flavored Markdown) extensions: tables, fenced code, footnotes, and more
- Syntax highlighting via Pygments with configurable styles
- Automatic table of contents generation with permalink anchors
- Custom CSS support or built-in GitHub-style theme
- Complete HTML document output with proper metadata

markdown==3.5.2
Pygments==2.17.2