mddoco 0.1.0__tar.gz

mddoco-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,149 @@
+# 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/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mddoco"
+version = "0.1.0"
+description = "Markdown to HTML/PDF document converter"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.0",
+    "markdown>=3.5",
+    "jinja2>=3.1",
+    "playwright>=1.40",
+    "matplotlib>=3.7",
+]
+
+[project.scripts]
+mddoco = "mddoco.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mddoco = ["themes/*.html"]
+
+[tool.ruff]
+src = ["src"]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

mddoco-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mddoco-0.1.0/src/mddoco/__init__.py

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

mddoco-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)