mddoco 0.1.0__py3-none-any.whl

mddoco/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mddoco/cli.py

@@ -0,0 +1,92 @@
+from pathlib import Path
+
+import click
+
+from mddoco.converter import convert_files
+from mddoco.pdf import html_to_pdf
+from mddoco.renderer import render_html
+from mddoco.scanner import find_markdown_files
+from mddoco.toc import combine_toc
+from mddoco.writer import write_output
+
+
+@click.command()
+@click.argument("input_path", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--output", "-o", "output_path",
+    default=".", show_default=True,
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Directory to write the output file.",
+)
+@click.option(
+    "--format", "-f", "fmt",
+    default="html", show_default=True,
+    type=click.Choice(["html", "pdf"], case_sensitive=False),
+    help="Output format.",
+)
+@click.option("--title", "-t", default=None, help="Document title.")
+@click.option(
+    "--theme",
+    default="default", show_default=True,
+    help="Theme name to use for rendering.",
+)
+@click.option(
+    "--toc/--no-toc",
+    default=False, show_default=True,
+    help="Generate a table of contents.",
+)
+@click.option(
+    "--toc-depth",
+    default=3, show_default=True,
+    type=click.IntRange(1, 6),
+    help="Maximum heading depth included in the TOC.",
+)
+def main(
+    input_path: Path,
+    output_path: Path,
+    fmt: str,
+    title: str | None,
+    theme: str,
+    toc: bool,
+    toc_depth: int,
+) -> None:
+    """Convert markdown files in INPUT_PATH to a single document."""
+    try:
+        md_files = find_markdown_files(input_path)
+    except (ValueError, FileNotFoundError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    click.echo(f"Found {len(md_files)} markdown file(s).")
+
+    raw = convert_files(md_files, toc=toc, toc_depth=toc_depth)
+    sections = [(p, html) for p, html, _ in raw]
+    toc_html = combine_toc([t for _, _, t in raw]) if toc else None
+    has_mermaid = any('<div class="mermaid">' in html for _, html in sections)
+
+    resolved = input_path.resolve()
+    stem = resolved.stem if resolved.is_file() else resolved.name
+
+    try:
+        content = render_html(
+            sections,
+            title=title,
+            toc_html=toc_html or None,
+            theme=theme,
+            has_mermaid=has_mermaid,
+        )
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if fmt == "html":
+        output_file = write_output(content, output_path, f"{stem}.html")
+        click.echo(f"Written to {output_file}")
+
+    elif fmt == "pdf":
+        output_path.mkdir(parents=True, exist_ok=True)
+        dest = output_path / f"{stem}.pdf"
+        click.echo("Rendering PDF...")
+        try:
+            html_to_pdf(content, dest)
+        except RuntimeError as exc:
+            raise click.ClickException(str(exc)) from exc
+        click.echo(f"Written to {dest}")

mddoco/converter.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+
+import markdown
+
+from mddoco.graph import process_graph
+from mddoco.mermaid import process_mermaid
+
+
+def convert_file(
+    path: Path,
+    toc: bool = False,
+    toc_depth: int = 3,
+) -> tuple[str, str]:
+    """Convert a markdown file to an HTML fragment.
+
+    Returns (html_body, toc_html). toc_html is empty when toc=False.
+    """
+    text = path.read_text(encoding="utf-8")
+
+    extensions = ["tables", "fenced_code", "attr_list"]
+    extension_configs: dict = {}
+
+    if toc:
+        extensions.append("toc")
+        extension_configs["toc"] = {"toc_depth": toc_depth}
+
+    md = markdown.Markdown(extensions=extensions, extension_configs=extension_configs)
+    html = md.convert(text)
+    html, _ = process_mermaid(html)
+    html, _ = process_graph(html)
+
+    toc_html: str = md.toc if toc else ""
+    return html, toc_html
+
+
+def convert_files(
+    paths: list[Path],
+    toc: bool = False,
+    toc_depth: int = 3,
+) -> list[tuple[Path, str, str]]:
+    """Convert markdown files, returning (path, html_body, toc_html) tuples."""
+    results = []
+    for p in paths:
+        html, toc_html = convert_file(p, toc=toc, toc_depth=toc_depth)
+        results.append((p, html, toc_html))
+    return results

mddoco/graph.py

@@ -0,0 +1,117 @@
+import io
+import json
+import re
+from html import escape, unescape
+
+import matplotlib
+matplotlib.use('Agg')  # non-interactive backend — must be set before importing pyplot
+import matplotlib.pyplot as plt
+
+_DEFAULT_COLOURS = [
+    '#2d6cbe', '#e74c3c', '#27ae60', '#e67e22',
+    '#8e44ad', '#16a085', '#2c3e50', '#d35400',
+]
+
+
+def graph_it(data, output=None):
+    dpi = 100
+    width_px = data.get('width_px', 640)
+    height_px = data.get('height_px', 480)
+    fig, ax = plt.subplots(figsize=(width_px / dpi, height_px / dpi), dpi=dpi)
+
+    orientation = data.get('orientation', 'vertical').lower()
+    if orientation not in ('horizontal', 'vertical'):
+        raise ValueError(
+            f"Invalid orientation '{orientation}' — must be 'horizontal' or 'vertical'"
+        )
+    horizontal = orientation == 'horizontal'
+
+    x = data['data']['x']
+
+    # Auto-generate series from data keys (everything except 'x') if not provided
+    series_list = data.get('series') or [
+        {'label': k} for k in data['data'] if k != 'x'
+    ]
+
+    for i, series in enumerate(series_list):
+        label = series['label']
+        values = data['data'][label]
+        series_type = series.get('type', 'line')
+        colour = series.get('colour', _DEFAULT_COLOURS[i % len(_DEFAULT_COLOURS)])
+
+        if series_type == 'bar':
+            colour_val = colour if isinstance(colour, list) else [colour] * len(values)
+            if horizontal:
+                ax.barh(x, values, color=colour_val, label=label)
+            else:
+                ax.bar(x, values, color=colour_val, label=label)
+        elif series_type in ('line', 'line2'):
+            marker = 'o' if series.get('marker', False) else 'None'
+            linestyle = ':' if series_type == 'line2' else '-'
+            if horizontal:
+                ax.plot(values, x, color=colour, marker=marker, linewidth=2, linestyle=linestyle, label=label)
+            else:
+                ax.plot(x, values, color=colour, marker=marker, linewidth=2, linestyle=linestyle, label=label)
+
+    if 'min' in data or 'max' in data:
+        lo = data.get('min', None)
+        hi = data.get('max', None)
+        if horizontal:
+            ax.set_xlim(lo, hi)
+        else:
+            ax.set_ylim(lo, hi)
+
+    title = data.get('title', '')
+    if title:
+        ax.set_title(title)
+
+    if data.get('show_legend', True):
+        ax.legend(loc='upper left')
+
+    ax.spines['top'].set_visible(False)
+    ax.spines['right'].set_visible(False)
+
+    if output:
+        plt.savefig(output, format="svg", bbox_inches='tight')
+        plt.close(fig)
+    else:
+        buf = io.StringIO()
+        plt.savefig(buf, format="svg", bbox_inches='tight')
+        plt.close(fig)
+        return buf.getvalue()
+
+
+_GRAPH_BLOCK = re.compile(
+    r'<pre><code class="language-graph">(.*?)</code></pre>',
+    re.DOTALL,
+)
+
+_SVG_HEADER = re.compile(r'^.*?(?=<svg)', re.DOTALL)
+
+
+def _render_graph(source: str) -> str:
+    """Parse JSON source, render via graph_it, and return an inline SVG element."""
+    data = json.loads(unescape(source))
+    svg = graph_it(data)
+    svg = _SVG_HEADER.sub('', svg)  # strip XML declaration and DOCTYPE
+    return f'<div class="graph">{svg}</div>'
+
+
+def process_graph(html: str) -> tuple[str, bool]:
+    """Replace fenced graph blocks with rendered SVG charts.
+
+    Falls back to an inline error message if the block cannot be parsed or rendered.
+    Returns (processed_html, found).
+    """
+    found = bool(_GRAPH_BLOCK.search(html))
+
+    def replace(m: re.Match) -> str:
+        try:
+            return _render_graph(m.group(1))
+        except Exception as exc:
+            return (
+                f'<p class="graph-error"><strong>Graph error:</strong> '
+                f'{escape(str(exc))}</p>'
+            )
+
+    return _GRAPH_BLOCK.sub(replace, html), found

mddoco/mermaid.py

@@ -0,0 +1,20 @@
+import re
+
+_MERMAID_BLOCK = re.compile(
+    r'<pre><code class="language-mermaid">(.*?)</code></pre>',
+    re.DOTALL,
+)
+
+
+def process_mermaid(html: str) -> tuple[str, bool]:
+    """Replace fenced mermaid blocks with Mermaid.js div elements.
+
+    Returns (processed_html, found) where found indicates whether any
+    mermaid blocks were present.
+    """
+    found = bool(_MERMAID_BLOCK.search(html))
+    processed = _MERMAID_BLOCK.sub(
+        lambda m: f'<div class="mermaid">{m.group(1)}</div>',
+        html,
+    )
+    return processed, found

mddoco/pdf.py

@@ -0,0 +1,33 @@
+import tempfile
+from pathlib import Path
+
+
+def html_to_pdf(html_content: str, dest: Path) -> None:
+    """Render an HTML string to a PDF file using a headless Chromium browser.
+
+    Navigates via a temporary file:// URL so that external resources (CDN
+    scripts, Mermaid.js, etc.) load correctly before the page is printed.
+    """
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        raise RuntimeError(
+            "Playwright is required for PDF output. "
+            "Run: pip install playwright && playwright install chromium"
+        )
+
+    with tempfile.NamedTemporaryFile(
+        suffix=".html", delete=False, mode="w", encoding="utf-8"
+    ) as f:
+        f.write(html_content)
+        tmp_path = Path(f.name)
+
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch()
+            page = browser.new_page()
+            page.goto(tmp_path.as_uri(), wait_until="networkidle")
+            page.pdf(path=str(dest), format="A4", print_background=True)
+            browser.close()
+    finally:
+        tmp_path.unlink(missing_ok=True)

mddoco/renderer.py

@@ -0,0 +1,33 @@
+from importlib.resources import files
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, TemplateNotFound
+
+
+def _make_env() -> Environment:
+    themes_dir = files("mddoco").joinpath("themes")
+    return Environment(
+        loader=FileSystemLoader(str(themes_dir)),
+        autoescape=True,
+    )
+
+
+def render_html(
+    sections: list[tuple[Path, str]],
+    title: str | None = None,
+    toc_html: str | None = None,
+    theme: str = "default",
+    has_mermaid: bool = False,
+) -> str:
+    """Render a full HTML document from (path, html_fragment) pairs."""
+    env = _make_env()
+    try:
+        template = env.get_template(f"{theme}.html")
+    except TemplateNotFound:
+        raise ValueError(f"Theme '{theme}' not found.")
+    return template.render(
+        title=title,
+        toc_html=toc_html,
+        sections=sections,
+        has_mermaid=has_mermaid,
+    )

mddoco/scanner.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+
+def find_markdown_files(input_path: Path) -> list[Path]:
+    """Return markdown files to process.
+
+    If input_path is a file, return it directly (must be a .md file).
+    If input_path is a directory, return all *.md files sorted by relative path.
+    """
+    if input_path.is_file():
+        if input_path.suffix.lower() != ".md":
+            raise ValueError(f"File is not a markdown file: {input_path}")
+        return [input_path]
+
+    if input_path.is_dir():
+        files = sorted(input_path.rglob("*.md"))
+        if not files:
+            raise FileNotFoundError(f"No markdown files found in: {input_path}")
+        return files
+
+    raise ValueError(f"Input path does not exist: {input_path}")

mddoco/themes/default.html

@@ -0,0 +1,167 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% if title %}{{ title }}{% else %}Document{% endif %}</title>
+    <style>
+        *, *::before, *::after { box-sizing: border-box; }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, sans-serif;
+            font-size: 16px;
+            line-height: 1.7;
+            color: #24292e;
+            margin: 0;
+            padding: 2rem 1rem;
+            background: #fff;
+        }
+
+        .container {
+            max-width: 860px;
+            margin: 0 auto;
+        }
+
+        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; }
+        h4 { font-size: 1em; }
+
+        .doc-title {
+            font-size: 2.5em;
+            margin-top: 0;
+            border-bottom: 2px solid #24292e;
+        }
+
+        a { color: #0366d6; text-decoration: none; }
+        a:hover { text-decoration: underline; }
+
+        p { margin: 0.75em 0; }
+
+        code {
+            font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+            font-size: 0.875em;
+            background: #f6f8fa;
+            padding: 0.2em 0.4em;
+            border-radius: 3px;
+        }
+
+        pre {
+            background: #f6f8fa;
+            border: 1px solid #eaecef;
+            border-radius: 6px;
+            padding: 1rem;
+            overflow-x: auto;
+            line-height: 1.45;
+        }
+
+        pre code {
+            background: none;
+            padding: 0;
+            border-radius: 0;
+            font-size: 0.875em;
+        }
+
+        table {
+            border-collapse: collapse;
+            width: 100%;
+            margin: 1em 0;
+            outline: 1px solid #c8ccd0;
+        }
+        th, td {
+            border: 1px solid #c8ccd0;
+            padding: 0.5em 1em;
+            text-align: left;
+        }
+        th { background: #f0f3f6; font-weight: 600; }
+        tr:nth-child(even) td { background: #fafbfc; }
+
+        blockquote {
+            margin: 1em 0;
+            padding: 0.5em 1em;
+            border-left: 4px solid #dfe2e5;
+            color: #6a737d;
+        }
+        blockquote p { margin: 0; }
+
+        img { max-width: 100%; height: auto; }
+
+        ul, ol { padding-left: 1.5em; margin: 0.75em 0; }
+        li { margin: 0.25em 0; }
+
+        hr, .section-divider {
+            border: none;
+            border-top: 1px solid #eaecef;
+            margin: 3rem 0;
+        }
+
+        /* Table of Contents */
+        .toc-block {
+            background: #f6f8fa;
+            border: 1px solid #eaecef;
+            border-radius: 6px;
+            padding: 1rem 1.5rem;
+            margin: 1.5rem 0 2.5rem;
+            display: inline-block;
+            min-width: 260px;
+        }
+        .toc-block .toc-heading {
+            font-size: 0.75em;
+            font-weight: 700;
+            text-transform: uppercase;
+            letter-spacing: 0.08em;
+            color: #6a737d;
+            margin: 0 0 0.5rem;
+        }
+        .toc-block ul {
+            margin: 0;
+            padding-left: 1.25em;
+            list-style: none;
+        }
+        .toc-block ul ul { padding-left: 1em; }
+        .toc-block li { margin: 0.2em 0; }
+        .toc-block a { color: #0366d6; font-size: 0.9em; }
+
+        /* Mermaid diagrams */
+        .mermaid {
+            text-align: center;
+            margin: 1.5em 0;
+        }
+    </style>
+    {% if has_mermaid %}
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <script>mermaid.initialize({ startOnLoad: true, theme: 'default' });</script>
+    {% endif %}
+</head>
+<body>
+    <div class="container">
+
+        {% if title %}
+        <h1 class="doc-title">{{ title }}</h1>
+        {% endif %}
+
+        {% if toc_html %}
+        <nav class="toc-block" aria-label="Table of contents">
+            <p class="toc-heading">Contents</p>
+            {{ toc_html | safe }}
+        </nav>
+        {% endif %}
+
+        <main>
+            {% for path, body in sections %}
+                {% if not loop.first %}
+                <hr class="section-divider">
+                {% endif %}
+                <section>{{ body | safe }}</section>
+            {% endfor %}
+        </main>
+
+    </div>
+</body>
+</html>

mddoco/themes/professional.html

@@ -0,0 +1,230 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% if title %}{{ title }}{% else %}Document{% endif %}</title>
+    <style>
+        *, *::before, *::after { box-sizing: border-box; }
+
+        :root {
+            --primary:  #1a3a5c;
+            --accent:   #2d6cbe;
+            --accent-light: #e8f0fb;
+            --border:   #b0bec5;
+            --muted:    #546e7a;
+            --bg:       #ffffff;
+            --bg-alt:   #f4f6f8;
+        }
+
+        body {
+            font-family: 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+            font-size: 15px;
+            line-height: 1.75;
+            color: #263238;
+            margin: 0;
+            padding: 0;
+            background: var(--bg-alt);
+        }
+
+        .page-wrap {
+            max-width: 900px;
+            margin: 2rem auto;
+            background: var(--bg);
+            border: 1px solid var(--border);
+            border-radius: 4px;
+            box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+        }
+
+        /* ── Title banner ─────────────────────────────────────────── */
+        .doc-header {
+            background: var(--primary);
+            color: #fff;
+            padding: 2.5rem 3rem 2rem;
+            border-radius: 4px 4px 0 0;
+        }
+        .doc-header .doc-title {
+            font-size: 2rem;
+            font-weight: 700;
+            letter-spacing: 0.02em;
+            margin: 0;
+            color: #fff;
+            border: none;
+        }
+        .doc-header .doc-subtitle {
+            margin: 0.4rem 0 0;
+            font-size: 0.9rem;
+            opacity: 0.7;
+            letter-spacing: 0.03em;
+        }
+
+        .content {
+            padding: 2rem 3rem 3rem;
+        }
+
+        /* ── Headings ──────────────────────────────────────────────── */
+        h1, h2, h3, h4, h5, h6 {
+            font-weight: 700;
+            line-height: 1.25;
+            margin-top: 2em;
+            margin-bottom: 0.5em;
+        }
+        h1 {
+            font-size: 1.75em;
+            color: var(--primary);
+            border-bottom: 3px solid var(--accent);
+            padding-bottom: 0.35em;
+        }
+        h2 {
+            font-size: 1.35em;
+            color: var(--accent);
+            border-bottom: 1px solid var(--border);
+            padding-bottom: 0.25em;
+        }
+        h3 { font-size: 1.1em;  color: var(--primary); }
+        h4 { font-size: 1em;    color: var(--muted); }
+
+        a { color: var(--accent); text-decoration: none; }
+        a:hover { text-decoration: underline; }
+
+        p { margin: 0.75em 0; }
+
+        /* ── Code ──────────────────────────────────────────────────── */
+        code {
+            font-family: 'Cascadia Code', 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+            font-size: 0.85em;
+            background: var(--bg-alt);
+            border: 1px solid var(--border);
+            padding: 0.15em 0.4em;
+            border-radius: 3px;
+        }
+        pre {
+            background: #1e2a38;
+            border-radius: 4px;
+            padding: 1.25rem;
+            overflow-x: auto;
+            line-height: 1.5;
+        }
+        pre code {
+            background: none;
+            border: none;
+            padding: 0;
+            font-size: 0.875em;
+            color: #cdd9e5;
+        }
+
+        /* ── Tables ────────────────────────────────────────────────── */
+        table {
+            border-collapse: collapse;
+            width: 100%;
+            margin: 1.25em 0;
+            outline: 1px solid var(--border);
+            border-radius: 4px;
+            overflow: hidden;
+        }
+        th {
+            background: var(--primary);
+            color: #fff;
+            font-weight: 600;
+            padding: 0.6em 1em;
+            text-align: left;
+            border: 1px solid #2a4f78;
+        }
+        td {
+            padding: 0.55em 1em;
+            border: 1px solid var(--border);
+        }
+        tr:nth-child(even) td { background: var(--accent-light); }
+        tr:hover td { background: #dde8f7; }
+
+        /* ── Blockquote ────────────────────────────────────────────── */
+        blockquote {
+            margin: 1em 0;
+            padding: 0.75em 1.25em;
+            border-left: 4px solid var(--accent);
+            background: var(--accent-light);
+            color: var(--muted);
+            border-radius: 0 4px 4px 0;
+        }
+        blockquote p { margin: 0; }
+
+        img { max-width: 100%; height: auto; }
+
+        ul, ol { padding-left: 1.5em; margin: 0.75em 0; }
+        li { margin: 0.3em 0; }
+
+        hr, .section-divider {
+            border: none;
+            border-top: 1px solid var(--border);
+            margin: 2.5rem 0;
+        }
+
+        /* ── Table of Contents ─────────────────────────────────────── */
+        .toc-block {
+            background: var(--accent-light);
+            border: 1px solid #b3c8ee;
+            border-left: 4px solid var(--accent);
+            border-radius: 0 4px 4px 0;
+            padding: 1rem 1.5rem;
+            margin: 1.5rem 0 2.5rem;
+            display: inline-block;
+            min-width: 280px;
+        }
+        .toc-block .toc-heading {
+            font-size: 0.7em;
+            font-weight: 700;
+            text-transform: uppercase;
+            letter-spacing: 0.1em;
+            color: var(--accent);
+            margin: 0 0 0.5rem;
+        }
+        .toc-block ul {
+            margin: 0;
+            padding-left: 1.25em;
+            list-style: none;
+        }
+        .toc-block ul ul { padding-left: 1em; }
+        .toc-block li { margin: 0.2em 0; }
+        .toc-block a { color: var(--primary); font-size: 0.9em; }
+        .toc-block a:hover { color: var(--accent); }
+
+        /* ── Mermaid ───────────────────────────────────────────────── */
+        .mermaid { text-align: center; margin: 1.5em 0; }
+    </style>
+    {% if has_mermaid %}
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <script>mermaid.initialize({ startOnLoad: true, theme: 'neutral' });</script>
+    {% endif %}
+</head>
+<body>
+    <div class="page-wrap">
+
+        {% if title %}
+        <header class="doc-header">
+            <h1 class="doc-title">{{ title }}</h1>
+            <p class="doc-subtitle">Generated by mddoco</p>
+        </header>
+        {% endif %}
+
+        <div class="content">
+
+            {% if toc_html %}
+            <nav class="toc-block" aria-label="Table of contents">
+                <p class="toc-heading">Contents</p>
+                {{ toc_html | safe }}
+            </nav>
+            {% endif %}
+
+            <main>
+                {% for path, body in sections %}
+                    {% if not loop.first %}
+                    <hr class="section-divider">
+                    {% endif %}
+                    <section>{{ body | safe }}</section>
+                {% endfor %}
+            </main>
+
+        </div>
+    </div>
+</body>
+</html>

mddoco/toc.py

@@ -0,0 +1,15 @@
+import re
+
+_INNER_UL = re.compile(r"<ul>(.*)</ul>", re.DOTALL)
+
+
+def combine_toc(fragments: list[str]) -> str:
+    """Merge per-file TOC HTML fragments into a single <ul> block."""
+    items: list[str] = []
+    for fragment in fragments:
+        m = _INNER_UL.search(fragment)
+        if m:
+            items.append(m.group(1).strip())
+    if not items:
+        return ""
+    return "<ul>\n" + "\n".join(items) + "\n</ul>"

mddoco/writer.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+
+def write_output(content: str, output_path: Path, filename: str) -> Path:
+    """Write content to output_path/filename, creating directories as needed."""
+    output_path.mkdir(parents=True, exist_ok=True)
+    dest = output_path / filename
+    dest.write_text(content, encoding="utf-8")
+    return dest

mddoco-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: mddoco
+Version: 0.1.0
+Summary: Markdown to HTML/PDF document converter
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: markdown>=3.5
+Requires-Dist: jinja2>=3.1
+Requires-Dist: playwright>=1.40
+Requires-Dist: matplotlib>=3.7
+Dynamic: license-file
+
+# mddoco
+
+A CLI tool that converts markdown files to a single HTML (or future PDF) document.
+
+## Installation
+
+```bash
+pip install mddoco
+playwright install chromium
+```
+
+Or for development:
+
+```bash
+pip install -e .
+playwright install chromium
+```
+
+> Playwright (Chromium) is required for PDF output only. HTML output works without it.
+
+## Usage
+
+```
+mddoco [OPTIONS] INPUT_PATH
+```
+
+`INPUT_PATH` can be a **directory** (all `*.md` files are found recursively and sorted) or a **single `.md` file**.
+
+### Options
+
+| Option | Short | Default | Description |
+|---|---|---|---|
+| `--output PATH` | `-o` | `.` | Directory to write the output file |
+| `--format [html\|pdf]` | `-f` | `html` | Output format |
+| `--title TEXT` | `-t` | _(none)_ | Document title shown at the top of the page |
+| `--theme NAME` | | `default` | Theme to use for rendering |
+| `--toc / --no-toc` | | off | Generate a table of contents |
+| `--toc-depth N` | | `3` | Maximum heading depth included in the TOC (1–6) |
+
+### Examples
+
+Convert all markdown files in a directory:
+
+```bash
+mddoco ./docs
+```
+
+Convert a single file:
+
+```bash
+mddoco README.md
+```
+
+With a title, TOC, and custom output directory:
+
+```bash
+mddoco ./docs --title "My Project" --toc --output ./out
+```
+
+## Output
+
+All matched markdown files are combined into a single HTML document in the output directory. The filename is derived from the input folder or file name.
+
+## Themes
+
+Themes are self-contained Jinja2 HTML files with embedded CSS. The `default` theme includes:
+
+- Clean typographic layout
+- Syntax-highlighted code blocks
+- Styled tables and blockquotes
+- Optional document title
+- Optional table of contents
+- [Mermaid.js](https://mermaid.js.org) diagram support (loaded only when diagrams are present)
+
+### Graph diagrams
+
+Use ` ```graph ` fenced blocks with a JSON payload. The only required field is `data`.
+
+**Minimal example** — all defaults applied:
+
+````markdown
+```graph
+{
+  "data": {
+    "x": ["Jan", "Feb", "Mar"],
+    "Sales": [100, 150, 120]
+  }
+}
+```
+````
+
+Series are inferred from the data keys (everything except `x`). Each series defaults to a line chart in blue.
+
+**Full schema:**
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `data.x` | yes | — | Category labels |
+| `data.<name>` | yes | — | Values for each series (one key per series) |
+| `title` | no | _(none)_ | Chart title |
+| `orientation` | no | `vertical` | `vertical` or `horizontal` |
+| `show_legend` | no | `true` | Show the legend |
+| `width_px` | no | `640` | Width in pixels |
+| `height_px` | no | `480` | Height in pixels |
+| `min` / `max` | no | — | Axis bounds |
+| `series` | no | _(auto)_ | Override series definitions (see below) |
+
+**Series fields** (all optional when auto-generated):
+
+| Field | Default | Description |
+|---|---|---|
+| `label` | _(data key)_ | Must match a key in `data` |
+| `type` | `line` | `bar`, `line` (solid), or `line2` (dotted) |
+| `colour` | _(palette)_ | Colour string, or list of colours per bar |
+| `marker` | `false` | Show point markers (line types only) |
+
+**Full example:**
+
+````markdown
+```graph
+{
+  "title": "Sales vs Target",
+  "orientation": "vertical",
+  "show_legend": true,
+  "data": {
+    "x": ["Jan", "Feb", "Mar", "Apr", "May"],
+    "Sales":  [85, 92, 78, 96, 110],
+    "Target": [90, 90, 90, 90, 90]
+  },
+  "series": [
+    { "label": "Sales",  "type": "bar",  "colour": "#3498db" },
+    { "label": "Target", "type": "line", "colour": "#e74c3c", "marker": false }
+  ]
+}
+```
+````
+
+### Mermaid diagrams
+
+Use standard fenced code blocks in your markdown:
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B[End]
+```
+````
+
+mddoco detects mermaid blocks automatically and loads the Mermaid.js CDN only when needed.

mddoco-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+mddoco/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+mddoco/cli.py,sha256=dzlJd3EbaMlf2SZFhA_LTfs0Z7ZcPlnC0L89V7iUgfA,2790
+mddoco/converter.py,sha256=_82oF32T-uc9AazSj1DIs_8d-SNR4476Jcan_3l8uTA,1231
+mddoco/graph.py,sha256=x9VpO2-bajmzQxqJkmIgl2M8u8dC_neoJ4dKfdaWRo8,3814
+mddoco/mermaid.py,sha256=bWq3nY19PhkSS2_3xR3Md34tsIk_rZ7mi6kKyDxHthg,545
+mddoco/pdf.py,sha256=a-O1Xbd35xmCCF4_YJs5yzPdt-KgZgjlWUSWQq4a2XY,1115
+mddoco/renderer.py,sha256=l3kt4aKQWeXOD-kAr388K7rqGUacaQk9HPmstMsjWx0,894
+mddoco/scanner.py,sha256=EX3RTMQGZrAb6xOlVQvdjaA9-xErRntf7zFg5mvLyPk,732
+mddoco/toc.py,sha256=4h3lSjPmWvdwWeRgX6-nCikenF0QVayZ8Aqd_0pbYUA,423
+mddoco/writer.py,sha256=KnTaFm3BI-Skx-UDZmUJNV7JI9f1Pq8fwOOoAyDvKp0,330
+mddoco/themes/default.html,sha256=ePIOAIm7A7zwCSeRM4qomLQRlk7ie4uLPojHQN0ywlQ,4641
+mddoco/themes/professional.html,sha256=8cwh-3L3bcBIRmjZ57Iw8FwI3X8UUKcH4_0J0C110NI,7661
+mddoco-0.1.0.dist-info/licenses/LICENSE,sha256=JTTt6kL0A6OVPRn5wc8igU30mo5Wi2wZ2wai5dcY3H0,1068
+mddoco-0.1.0.dist-info/METADATA,sha256=4KAzsXwFmSDFJv4IMfjEzM_I4hWkd1HCOlE9K4ZUz54,4084
+mddoco-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mddoco-0.1.0.dist-info/entry_points.txt,sha256=PbJ-QZBElwOzXK1NpkO07SdArunbFgyPycv4_UxPAko,43
+mddoco-0.1.0.dist-info/top_level.txt,sha256=Eg5Eig5yjjCYwuJ1D3NnrHnnMBJo83ryWd_tPVNtbOo,7
+mddoco-0.1.0.dist-info/RECORD,,

mddoco-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mddoco-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mddoco = mddoco.cli:main

mddoco-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phil Massyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mddoco-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mddoco