{html_lib.escape(m.group(1))}")
text = _RE_CODE_INLINE.sub(_code_sub, text)
# 1b. Display math (passthrough; MathJax will render).
def _md_sub(m: re.Match[str]) -> str:
body = m.group(1)
return store(f"$${body}$$")
text = _RE_MATH_DISPLAY.sub(_md_sub, text)
# 1c. Inline math (passthrough).
def _mi_sub(m: re.Match[str]) -> str:
body = m.group(1)
return store(f"${body}$")
text = _RE_MATH_INLINE.sub(_mi_sub, text)
# 1d. Wikilink paper refs [[key]] or [[key|display]] — stash as a clickable
# span with data-ref="key". The template JS wires up the popover from
# window.PAPER_REGISTRY (sidecar JSON loaded via --papers). Default display
# is the key uppercased; explicit display via |label form.
def _ref_sub(m: re.Match[str]) -> str:
key = m.group(1)
display = m.group(2) if m.group(2) is not None else key.upper()
return store(
f'{html_lib.escape(display)}'
)
text = _RE_PAPER_REF.sub(_ref_sub, text)
# 1e. Inline HTML spans (very limited allowlist + sanitize before stash).
_re_tag = re.compile(
r"<(/?)(" + "|".join(_INLINE_HTML_TAGS) + r")(\s[^<>]*)?>",
re.IGNORECASE,
)
def _tag_sub(m: re.Match[str]) -> str:
return store(sanitize_html(m.group(0)))
text = _re_tag.sub(_tag_sub, text)
# 2. HTML-escape remainder.
text = html_lib.escape(text, quote=False)
# 3. Apply markdown emphasis & links.
def _img_sub(m: re.Match[str]) -> str:
alt = html_lib.escape(m.group(1), quote=True)
src = html_lib.escape(_safe_url(m.group(2)), quote=True)
title = m.group(3)
title_attr = f' title="{html_lib.escape(title, quote=True)}"' if title else ""
return f'` inside backticks
# in a paragraph don't perturb the counter.
if _RE_HTML_BLOCK_OPEN.match(line):
tag_m = _RE_HTML_BLOCK_OPEN.match(line)
assert tag_m is not None
tag = tag_m.group(1).lower()
line_open_re = re.compile(rf"^\s*<{re.escape(tag)}(?=[\s/>])", re.IGNORECASE)
line_close_re = re.compile(rf"^\s*])", re.IGNORECASE)
body = [line]
depth = 1
# Self-closing tag on the same line: ... or on same line as open
elif re.search(rf"])", line, re.IGNORECASE):
depth = 0
i += 1
while i < n and depth > 0:
cur = lines[i]
body.append(cur)
# Count nested opens/closes at line start only.
if line_open_re.match(cur):
depth += 1
if line_close_re.match(cur):
depth -= 1
i += 1
content = "\n".join(body)
# Sanitize: strip dangerous tags / event handlers / unsafe URL schemes.
content = sanitize_html(content)
blocks.append({"type": "html", "content": content})
continue
# Blockquote.
if _RE_BLOCKQUOTE.match(stripped):
quote_lines: list[str] = []
while i < n:
m_bq = _RE_BLOCKQUOTE.match(lines[i].rstrip())
if not m_bq:
break
quote_lines.append(m_bq.group(1))
i += 1
blocks.append({"type": "blockquote", "lines": quote_lines})
continue
# Ordered or unordered list. Indent-aware: a marker at the same
# indent as the first item starts a sibling; a marker at deeper
# indent (or any deeper-indented continuation line) becomes part
# of the current item's content and is re-parsed recursively in
# render_list (so nested lists / paragraphs / code blocks work).
if _RE_ORDERED.match(stripped) or _RE_UNORDERED.match(stripped):
first_m = _RE_ORDERED.match(lines[i]) or _RE_UNORDERED.match(lines[i])
base_indent = len(first_m.group(1))
ordered = bool(_RE_ORDERED.match(lines[i]))
items: list[str] = []
current: list[str] = []
while i < n:
cur_line = lines[i]
# Blank line — peek ahead to decide if list continues.
if cur_line.strip() == "":
if i + 1 < n:
nxt = lines[i + 1]
m_o_next = _RE_ORDERED.match(nxt)
m_u_next = _RE_UNORDERED.match(nxt)
if (m_o_next or m_u_next) and len(
(m_o_next or m_u_next).group(1)
) >= base_indent:
# Continue list; consume blank.
current.append("")
i += 1
continue
if nxt.startswith(" " * (base_indent + 2)) or nxt.startswith("\t"):
current.append("")
i += 1
continue
break
m_o = _RE_ORDERED.match(cur_line)
m_u = _RE_UNORDERED.match(cur_line)
if m_o or m_u:
marker_indent = len((m_o or m_u).group(1))
if marker_indent == base_indent:
# Sibling item at same level.
if current:
items.append("\n".join(current).rstrip())
current = []
current.append((m_o or m_u).group(3 if m_o else 2))
i += 1
continue
if marker_indent > base_indent:
# Nested item — append the line with reduced indent
# (strip base_indent + 2 spaces so the nested parse
# sees the marker at column 0 of its own context).
strip = base_indent + 2
current.append(
cur_line[strip:] if cur_line[:strip].strip() == "" else cur_line.lstrip()
)
i += 1
continue
# Marker at shallower indent — list ends here.
break
# Non-marker line: continuation of current item if indented
# past base_indent + 2 (or any indent for the "lazy continuation"
# convention).
if cur_line.startswith(" " * (base_indent + 2)) or cur_line.startswith("\t"):
strip = base_indent + 2
current.append(
cur_line[strip:] if cur_line[:strip].strip() == "" else cur_line.lstrip()
)
i += 1
continue
# Anything else at base_indent or shallower → list ends.
break
if current:
items.append("\n".join(current).rstrip())
blocks.append({"type": "list", "ordered": ordered, "items": items})
continue
# Paragraph: gather lines until blank or block boundary.
para: list[str] = [stripped]
i += 1
while i < n:
nxt = lines[i].rstrip()
if not nxt.strip():
break
if (_RE_HEADING.match(nxt) or _RE_CODE_FENCE.match(nxt) or _RE_HR.match(nxt) or
_RE_BLOCKQUOTE.match(nxt) or _RE_ORDERED.match(nxt) or
_RE_UNORDERED.match(nxt) or _RE_HTML_BLOCK_OPEN.match(lines[i]) or
("|" in nxt and i + 1 < n and _RE_TABLE_DIVIDER.match(lines[i + 1].rstrip()))):
break
para.append(nxt)
i += 1
blocks.append({"type": "paragraph", "text": " ".join(para)})
return blocks
# ---------------------------------------------------------------------------
# Block rendering
# ---------------------------------------------------------------------------
def render_table(header: str, divider: str, rows: list[str]) -> str:
def split_row(s: str) -> list[str]:
s = s.strip()
if s.startswith("|"):
s = s[1:]
if s.endswith("|"):
s = s[:-1]
return [c.strip() for c in s.split("|")]
header_cells = split_row(header)
align = []
for cell in split_row(divider):
cell = cell.strip()
if cell.startswith(":") and cell.endswith(":"):
align.append("center")
elif cell.endswith(":"):
align.append("right")
else:
align.append("left")
def cell_attr(idx: int) -> str:
if idx < len(align) and align[idx] != "left":
return f' style="text-align:{align[idx]}"'
return ""
out: list[str] = ["", "
")
return "".join(out)
def render_blockquote(quote_lines: list[str]) -> str:
"""Detect callout style (emoji prefix) and render with callout class."""
if not quote_lines:
return ""
first = quote_lines[0]
css_class = None
title = None
body_lines = list(quote_lines)
# Try matching callout prefix on the first non-empty line.
first_nonempty_idx = 0
while first_nonempty_idx < len(body_lines) and not body_lines[first_nonempty_idx].strip():
first_nonempty_idx += 1
if first_nonempty_idx < len(body_lines):
line0 = body_lines[first_nonempty_idx].lstrip()
for pattern, klass, default_title in _CALLOUT_PREFIX_MAP:
m = pattern.match(line0)
if m:
css_class = klass
title = default_title
# Strip emoji + try to extract a **Bold:** title prefix.
rest = pattern.sub("", line0, count=1)
m_title = re.match(r"\*\*([^*\n]+?)\*\*[:：\s\-—]+\s*", rest)
if m_title:
title = m_title.group(1)
rest = rest[m_title.end():]
body_lines[first_nonempty_idx] = rest
break
inner_md = "\n".join(body_lines).strip("\n")
inner_blocks = parse_blocks(inner_md.split("\n")) if inner_md else []
inner_html, _ = _render_blocks(inner_blocks, collect_toc=False)
if css_class:
title_html = f'{render_inline(item_blocks[0]['text'])} ")
else:
inner, _ = _render_blocks(item_blocks, collect_toc=False)
out.append(f"{inner} ")
out.append(f"")
return "".join(out)
def render_code(lang: str, content: str, flags: set | None = None) -> str:
escaped = html_lib.escape(content)
# Per-block override for the auto-collapse JS in the template:
# ```python {collapsed} → force fold
# ```python {open} → force expanded
# Anything else leaves the decision to the auto-threshold (default 30 lines).
attr = ""
if flags:
if "collapsed" in flags:
attr = ' data-collapse="collapsed"'
elif "open" in flags:
attr = ' data-collapse="open"'
if lang:
return f'{inline} ')
if collect_toc and 2 <= level <= 3:
toc.append({"level": level, "id": uid, "text": text})
elif t == "paragraph":
out.append(f"
") elif t == "code": out.append(render_code(b.get("lang", ""), b["content"], b.get("flags"))) elif t == "blockquote": out.append(render_blockquote(b["lines"])) elif t == "list": out.append(render_list(b["ordered"], b["items"])) elif t == "table": out.append(render_table(b["header"], b["divider"], b["rows"])) elif t == "html": out.append(_render_html_block(b["content"])) else: out.append(f"") return "\n".join(out), toc def _render_html_block(content: str) -> str: """For
{html_lib.escape(title or "")}
' if title else ""
return f'{title_html}{inner_html}
'
return f"{inner_html}" def render_list(ordered: bool, items: list[str]) -> str: tag = "ol" if ordered else "ul" out = [f"<{tag}>"] for item in items: # Nested lists are possible — parse the item body as blocks. item_blocks = parse_blocks(item.split("\n")) # Common case: single paragraph — emit inline directly. if len(item_blocks) == 1 and item_blocks[0]["type"] == "paragraph": out.append(f"
{escaped}'
# Heuristic: if content looks like an ASCII art diagram (mostly box-drawing
# chars and pipes), tag the surrounding with class="diagram".
diagram_chars = set("│─┌┐└┘├┤┬┴┼▲▼◀▶━┃┏┓┗┛╭╮╰╯═║╔╗╚╝╠╣╦╩╬║▶▼─")
sample = content[:200]
if sample and sum(1 for c in sample if c in diagram_chars) >= 4:
return f'{escaped}'
return f"{escaped}"
def _render_blocks(
blocks: list[dict],
collect_toc: bool,
used_ids: dict | None = None,
) -> tuple[str, list[dict]]:
if used_ids is None:
used_ids = {}
out: list[str] = []
toc: list[dict] = []
for b in blocks:
t = b["type"]
if t == "heading":
level = b["level"]
text = b["text"]
inline = render_inline(text)
base_id = _slugify(text)
uid = base_id
n = used_ids.get(base_id, 0)
if n > 0:
uid = f"{base_id}-{n}"
used_ids[base_id] = n + 1
out.append(f'{render_inline(b['text'])}
") elif t == "hr": out.append("") elif t == "code": out.append(render_code(b.get("lang", ""), b["content"], b.get("flags"))) elif t == "blockquote": out.append(render_blockquote(b["lines"])) elif t == "list": out.append(render_list(b["ordered"], b["items"])) elif t == "table": out.append(render_table(b["header"], b["divider"], b["rows"])) elif t == "html": out.append(_render_html_block(b["content"])) else: out.append(f"") return "\n".join(out), toc def _render_html_block(content: str) -> str: """For
...
blocks, parse the inner content as Markdown.
Matches GitHub-flavored convention: when a `` block has a blank
line separating its `` from the body, the body is parsed as
markdown (lists, headings, code, callouts all work). For non-
` from the body, the body is parsed as
markdown (lists, headings, code, callouts all work). For non-
HTML blocks, content passes through verbatim.
"""
lines = content.split("\n")
if not lines or not lines[0].lstrip().lower().startswith(" if present, else after the
# line itself.
open_end = 1 # default: just past the line
summary_close_re = re.compile(r"", re.IGNORECASE)
for j in range(1, len(lines)):
if summary_close_re.search(lines[j]):
open_end = j + 1
break
# If we hit non-summary content first, no `` block; stop scanning.
if lines[j].strip() and not re.match(r"\s* line.
close_start = len(lines) - 1
close_re = re.compile(r"^\s*", re.IGNORECASE)
while close_start > 0 and not close_re.match(lines[close_start]):
close_start -= 1
if open_end >= close_start:
# Degenerate or empty body; emit raw.
return content
open_part = "\n".join(lines[:open_end])
inner_md = "\n".join(lines[open_end:close_start]).strip("\n")
close_part = "\n".join(lines[close_start:])
if not inner_md.strip():
return content
inner_blocks = parse_blocks(inner_md.split("\n"))
inner_html, _ = _render_blocks(inner_blocks, collect_toc=False)
return f"{open_part}\n{inner_html}\n{close_part}"
def render_toc(toc: list[dict]) -> str:
"""Render a nested TOC. Groups consecutive H3s under their preceding H2.
Orphan H3 (H3 without a preceding H2 in this run) is promoted to a
top-level . Output is well-formed `- ...
- ...
...
`.
"""
if not toc:
return ""
grouped: list[tuple[dict, list[dict]]] = [] # [(h2_entry, [h3_children])]
current_parent: dict | None = None
current_children: list[dict] = []
for entry in toc:
if entry["level"] == 2:
if current_parent is not None:
grouped.append((current_parent, current_children))
current_parent = entry
current_children = []
elif entry["level"] == 3:
if current_parent is None:
# Orphan H3 — promote to top level so the TOC stays well-formed.
grouped.append((entry, []))
else:
current_children.append(entry)
if current_parent is not None:
grouped.append((current_parent, current_children))
out: list[str] = [""]
for parent, children in grouped:
pid = html_lib.escape(parent["id"], quote=True)
ptext = html_lib.escape(parent["text"])
out.append(f'- {ptext}')
if children:
out.append("
")
for c in children:
cid = html_lib.escape(c["id"], quote=True)
ctext = html_lib.escape(c["text"])
out.append(f'- {ctext}
')
out.append("
")
out.append(" ")
out.append("
")
return "\n".join(out)
def strip_frontmatter(md: str) -> str:
"""Strip leading YAML frontmatter (--- ... ---) if present at start.
Also strips a leading UTF-8 BOM so frontmatter detection still fires
on files saved by editors that prepend it.
"""
md = md.lstrip("")
lines = md.split("\n", 1)
if not lines or lines[0].strip() != "---":
return md
# find closing ---
rest = lines[1] if len(lines) > 1 else ""
parts = rest.split("\n---\n", 1)
if len(parts) == 2:
return parts[1].lstrip("\n")
# try also \n--- at the very end of a line
parts = rest.split("\n---", 1)
if len(parts) == 2 and (parts[1] == "" or parts[1].startswith("\n")):
return parts[1].lstrip("\n")
return md
# ---------------------------------------------------------------------------
# Template loading + main
# ---------------------------------------------------------------------------
CDN_BLOCK_FULL = """
"""
CDN_BLOCK_OFFLINE = ""
def load_template(name: str) -> str:
path = TEMPLATES_DIR / f"{name}.html"
if not path.exists():
raise SystemExit(
f"error: template '{name}' not found at {path}. "
f"Available: {[p.stem for p in TEMPLATES_DIR.glob('*.html')]}"
)
return path.read_text(encoding="utf-8")
def sha256_of(text: str) -> str:
return hashlib.sha256(text.encode("utf-8")).hexdigest()
def render_json_as_pre(json_path: Path) -> str:
"""Render a sidecar JSON file as a collapsed block of pretty-printed JSON."""
try:
obj = json.loads(json_path.read_text(encoding="utf-8"))
except json.JSONDecodeError as e:
return f'JSON parse error{html_lib.escape(str(e))}
'
pretty = json.dumps(obj, ensure_ascii=False, indent=2, sort_keys=False)
return (
f'Sidecar JSON: {html_lib.escape(str(json_path))}
'
f'{html_lib.escape(pretty)}
'
f''
)
def substitute(template: str, vars: dict) -> str:
out = template
for k, v in vars.items():
out = out.replace("{{" + k + "}}", v)
return out
def json_for_script(obj: object) -> str:
"""Serialize JSON for direct embedding inside a classic '
will break out of the host
line itself.
open_end = 1 # default: just past the
line
summary_close_re = re.compile(r"", re.IGNORECASE)
for j in range(1, len(lines)):
if summary_close_re.search(lines[j]):
open_end = j + 1
break
# If we hit non-summary content first, no `` block; stop scanning.
if lines[j].strip() and not re.match(r"\s*
` block; stop scanning.
if lines[j].strip() and not re.match(r"\s* line.
close_start = len(lines) - 1
close_re = re.compile(r"^\s*", re.IGNORECASE)
while close_start > 0 and not close_re.match(lines[close_start]):
close_start -= 1
if open_end >= close_start:
# Degenerate or empty body; emit raw.
return content
open_part = "\n".join(lines[:open_end])
inner_md = "\n".join(lines[open_end:close_start]).strip("\n")
close_part = "\n".join(lines[close_start:])
if not inner_md.strip():
return content
inner_blocks = parse_blocks(inner_md.split("\n"))
inner_html, _ = _render_blocks(inner_blocks, collect_toc=False)
return f"{open_part}\n{inner_html}\n{close_part}"
def render_toc(toc: list[dict]) -> str:
"""Render a nested TOC. Groups consecutive H3s under their preceding H2.
Orphan H3 (H3 without a preceding H2 in this run) is promoted to a
top-level . Output is well-formed `- ...
- ...
...
`.
"""
if not toc:
return ""
grouped: list[tuple[dict, list[dict]]] = [] # [(h2_entry, [h3_children])]
current_parent: dict | None = None
current_children: list[dict] = []
for entry in toc:
if entry["level"] == 2:
if current_parent is not None:
grouped.append((current_parent, current_children))
current_parent = entry
current_children = []
elif entry["level"] == 3:
if current_parent is None:
# Orphan H3 — promote to top level so the TOC stays well-formed.
grouped.append((entry, []))
else:
current_children.append(entry)
if current_parent is not None:
grouped.append((current_parent, current_children))
out: list[str] = [""]
for parent, children in grouped:
pid = html_lib.escape(parent["id"], quote=True)
ptext = html_lib.escape(parent["text"])
out.append(f'- {ptext}')
if children:
out.append("
")
for c in children:
cid = html_lib.escape(c["id"], quote=True)
ctext = html_lib.escape(c["text"])
out.append(f'- {ctext}
')
out.append("
")
out.append(" ")
out.append("
")
return "\n".join(out)
def strip_frontmatter(md: str) -> str:
"""Strip leading YAML frontmatter (--- ... ---) if present at start.
Also strips a leading UTF-8 BOM so frontmatter detection still fires
on files saved by editors that prepend it.
"""
md = md.lstrip("")
lines = md.split("\n", 1)
if not lines or lines[0].strip() != "---":
return md
# find closing ---
rest = lines[1] if len(lines) > 1 else ""
parts = rest.split("\n---\n", 1)
if len(parts) == 2:
return parts[1].lstrip("\n")
# try also \n--- at the very end of a line
parts = rest.split("\n---", 1)
if len(parts) == 2 and (parts[1] == "" or parts[1].startswith("\n")):
return parts[1].lstrip("\n")
return md
# ---------------------------------------------------------------------------
# Template loading + main
# ---------------------------------------------------------------------------
CDN_BLOCK_FULL = """
"""
CDN_BLOCK_OFFLINE = ""
def load_template(name: str) -> str:
path = TEMPLATES_DIR / f"{name}.html"
if not path.exists():
raise SystemExit(
f"error: template '{name}' not found at {path}. "
f"Available: {[p.stem for p in TEMPLATES_DIR.glob('*.html')]}"
)
return path.read_text(encoding="utf-8")
def sha256_of(text: str) -> str:
return hashlib.sha256(text.encode("utf-8")).hexdigest()
def render_json_as_pre(json_path: Path) -> str:
"""Render a sidecar JSON file as a collapsed block of pretty-printed JSON."""
try:
obj = json.loads(json_path.read_text(encoding="utf-8"))
except json.JSONDecodeError as e:
return f'JSON parse error{html_lib.escape(str(e))}
'
pretty = json.dumps(obj, ensure_ascii=False, indent=2, sort_keys=False)
return (
f'Sidecar JSON: {html_lib.escape(str(json_path))}
'
f'{html_lib.escape(pretty)}
'
f''
)
def substitute(template: str, vars: dict) -> str:
out = template
for k, v in vars.items():
out = out.replace("{{" + k + "}}", v)
return out
def json_for_script(obj: object) -> str:
"""Serialize JSON for direct embedding inside a classic '
will break out of the host
- ...
- ...
- "]
for parent, children in grouped:
pid = html_lib.escape(parent["id"], quote=True)
ptext = html_lib.escape(parent["text"])
out.append(f'
- {ptext}')
if children:
out.append("
- ")
for c in children:
cid = html_lib.escape(c["id"], quote=True)
ctext = html_lib.escape(c["text"])
out.append(f'
- {ctext} ') out.append("
")
out.append("
block of pretty-printed JSON."""
try:
obj = json.loads(json_path.read_text(encoding="utf-8"))
except json.JSONDecodeError as e:
return f''
pretty = json.dumps(obj, ensure_ascii=False, indent=2, sort_keys=False)
return (
f'Sidecar JSON:
'
f''
)
def substitute(template: str, vars: dict) -> str:
out = template
for k, v in vars.items():
out = out.replace("{{" + k + "}}", v)
return out
def json_for_script(obj: object) -> str:
"""Serialize JSON for direct embedding inside a classic '
will break out of the host
JSON parse error
{html_lib.escape(str(e))}
Sidecar JSON: {html_lib.escape(str(json_path))}
'
f'{html_lib.escape(pretty)}