diff --git a/generate_html.py b/generate_html.py
new file mode 100644
index 0000000..095e788
--- /dev/null
+++ b/generate_html.py
@@ -0,0 +1,4 @@
+"""Thin wrapper so you can run `python generate_html.py ` from the repo root."""
+from src.utils.generate_html import main
+if __name__ == "__main__":
+ main()
diff --git a/src/utils/generate_html.py b/src/utils/generate_html.py
new file mode 100644
index 0000000..ca87166
--- /dev/null
+++ b/src/utils/generate_html.py
@@ -0,0 +1,635 @@
+"""
+HTML Generator
+Converts REPORT.md + figures into a self-contained styled HTML blog post.
+
+Usage:
+ python generate_html.py
+ python generate_html.py
+ python generate_html.py --output REPORT.html --title "My Experiment"
+"""
+
+import argparse
+import base64
+import mimetypes
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+# Dependency check
+def _check_deps():
+ missing = []
+ try:
+ import markdown # noqa: F401
+ except ImportError:
+ missing.append("markdown")
+ try:
+ import pygments # noqa: F401
+ except ImportError:
+ missing.append("pygments")
+ if missing:
+ print(f"[ERROR] Missing dependencies: {', '.join(missing)}")
+ print(f"Install with: pip install {' '.join(missing)}")
+ sys.exit(1)
+
+_check_deps()
+
+import markdown
+from markdown.extensions.codehilite import CodeHiliteExtension
+from markdown.extensions.fenced_code import FencedCodeExtension
+from markdown.extensions.tables import TableExtension
+from markdown.extensions.toc import TocExtension
+from pygments.formatters import HtmlFormatter
+
+
+# Figure discovery
+IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}
+FIGURE_DIRS = [".", "results", "figures", "paper_draft/figures", "plots", "output"]
+
+
+def _find_figure(name: str, base: Path) -> Path | None:
+ """Resolve an image reference relative to base, checking common figure dirs."""
+ candidate = (base / name).resolve()
+ if candidate.exists():
+ return candidate
+ for d in FIGURE_DIRS:
+ candidate = (base / d / Path(name).name).resolve()
+ if candidate.exists():
+ return candidate
+ return None
+
+
+def _embed_image(path: Path) -> str:
+ """Return a data URI for the given image file."""
+ mime, _ = mimetypes.guess_type(str(path))
+ mime = mime or "image/png"
+ data = base64.b64encode(path.read_bytes()).decode()
+ return f"data:{mime};base64,{data}"
+
+
+def _replace_image_refs(md_text: str, base: Path) -> str:
+ """Replace file-based image src attributes with base64 data URIs."""
+ def replacer(m):
+ alt, src = m.group(1), m.group(2)
+ if src.startswith("http://") or src.startswith("https://") or src.startswith("data:"):
+ return m.group(0)
+ resolved = _find_figure(src, base)
+ if resolved:
+ return f"})"
+ return m.group(0) # leave unchanged if not found
+
+ return re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", replacer, md_text)
+
+
+# md -> HTML
+def _ensure_blank_line_before_tables(text: str) -> str:
+ """Insert a blank line before table rows that aren't already preceded by one.
+
+ The nl2br extension prevents the tables extension from detecting pipe-table
+ syntax unless the table block is separated from the preceding text by a blank
+ line. This pre-pass normalises the markdown without touching the source file.
+ """
+ lines = text.splitlines()
+ out = []
+ for i, line in enumerate(lines):
+ if line.startswith("|") and i > 0 and out and out[-1].strip() != "":
+ # Only insert if the previous non-empty line is not itself a table row
+ prev = out[-1]
+ if not prev.startswith("|"):
+ out.append("")
+ out.append(line)
+ return "\n".join(out)
+
+
+def _convert_markdown(text: str) -> tuple[str, str]:
+ """Return (body_html, toc_html)."""
+ text = _ensure_blank_line_before_tables(text)
+ toc_ext = TocExtension(permalink=True, title="Contents")
+ hilite_ext = CodeHiliteExtension(guess_lang=False, linenums=False)
+ md = markdown.Markdown(
+ extensions=[
+ toc_ext,
+ hilite_ext,
+ FencedCodeExtension(),
+ TableExtension(),
+ "meta",
+ "nl2br",
+ "sane_lists",
+ "smarty",
+ ]
+ )
+ body = md.convert(text)
+ toc = md.toc # type: ignore[attr-defined]
+ return body, toc
+
+# Metadata extraction
+def _extract_title(md_text: str, fallback: str) -> str:
+ m = re.search(r"^#\s+(.+)$", md_text, re.MULTILINE)
+ return m.group(1).strip() if m else fallback
+
+
+def _extract_meta(workspace: Path) -> dict:
+ """Pull experiment metadata from idea.yaml if present."""
+ meta: dict = {}
+ idea_path = workspace / ".neurico" / "idea.yaml"
+ if not idea_path.exists():
+ return meta
+ try:
+ import yaml
+ data = yaml.safe_load(idea_path.read_text())
+ if isinstance(data, dict):
+ meta["domain"] = data.get("domain", "")
+ meta["author"] = data.get("author", "")
+ except Exception:
+ pass
+ return meta
+
+
+# CSS / HTML template
+def _pygments_css() -> str:
+ return HtmlFormatter(style="github-dark").get_style_defs(".codehilite")
+
+
+_HTML_TEMPLATE = """\
+
+
+
+
+
+ {title}
+
+
+
+
+
+
+
+
+
+
+
+ {meta_pills}
+
+ {body}
+
+
+