SENTINEL
paragraphs; each one is recorded in ``self.embeds`` so the caller can media-insert the real file in the correct position afterwards. """ def __init__(self, md_dir: Path, session_tag: str): super().__init__(convert_charrefs=True) self.md_dir = md_dir self.session_tag = session_tag self.out: list[str] = [] self.embeds: list[dict] = [] # {sentinel, file, type, caption} self._code_buf: list[str] | None = None self._code_lang: str | None = None self._table_buf: list[str] | None = None # we buffer the entire table so colspan/rowspan etc. just round-trip self._table_depth = 0 self._in_pre = False self._inline_stack: list[str] = [] self._li_stack: list[str] = [] # track ul/ol type for current li self._blockquote_depth = 0 self._p_depth = 0 # how manyare currently open in our output stream # ---- sentinel handling ---- def _next_sentinel(self) -> str: n = len(self.embeds) # All caps + underscores so it never collides with normal markdown prose return f"{SENTINEL_PREFIX}_{self.session_tag}_{n:04d}" def _resolve_local(self, src: str) -> Path | None: # Strip query/fragment for sanity clean = src.split("#", 1)[0].split("?", 1)[0] if not clean or is_http_url(clean) or is_anchor(clean): return None p = Path(clean) if not p.is_absolute(): p = (self.md_dir / p).resolve() return p if p.exists() and p.is_file() else None # ---- emit helpers ---- def _emit(self, s: str) -> None: # If we're buffering a table, append there instead if self._table_buf is not None: self._table_buf.append(s) else: self.out.append(s) def _emit_placeholder(self, file: Path, kind: str, caption: str | None = None) -> None: sentinel = self._next_sentinel() self.embeds.append({ "sentinel": sentinel, "file": str(file), "type": kind, "caption": caption, }) # The placeholder must end up as its own top-level
so media-insert # can anchor on it cleanly and the cleanup pass can block_delete it. # If we're currently inside a
, split: close, emit standalone, reopen. if self._table_buf is not None: # Inside a table cell — best we can do is emit the sentinel as # inline text and rely on str_replace cleanup. Media still lands at # top level (per --selection-with-ellipsis semantics). self._emit(sentinel) return if self._p_depth > 0: self.out.append("
") self.out.append(f"{sentinel}
") self.out.append("") return self._emit(f"
{sentinel}
") # ---- HTMLParser hooks ---- def handle_starttag(self, tag, attrs): attrd = dict(attrs) # Inside: capture verbatim
if self._in_pre:
# Don't recurse, but still record raw markup if any nested tags appear
if tag == "code":
self._code_lang = self._extract_lang(attrd.get("class", ""))
self._code_buf = []
return
# Table buffer mode: just copy markup through, no transformations needed
if self._table_buf is not None:
self._table_buf.append(self._raw_tag(tag, attrd))
if tag == "table":
self._table_depth += 1
return
if tag == "table":
self._table_buf = []
self._table_depth = 1
self._table_buf.append(self._raw_tag(tag, attrd))
return
if tag == "pre":
self._in_pre = True
return
if tag == "img":
self._emit_img(attrd)
return
if tag == "a":
href = attrd.get("href", "")
local = self._resolve_local(href) if href else None
if local is not None:
# Inline attachment: keep the link text in the prose so the
# paragraph still reads naturally, and queue a placeholder so
# the attachment block appears right after this paragraph.
caption = attrd.get("title") or None
self._emit_placeholder(local, "file", caption)
# Drop the tags (keep their text children) by pushing
# a "transparent" marker on the inline stack.
self._inline_stack.append("__TRANSPARENT_A__")
return
# Regular link
self._inline_stack.append("a")
attrs_s = self._attrs_string({"href": href})
self._emit(f"")
return
if tag in {"b", "strong"}:
self._inline_stack.append("b")
self._emit("")
return
if tag in {"em", "i"}:
self._inline_stack.append("em")
self._emit("")
return
if tag in {"u"}:
self._inline_stack.append("u")
self._emit("")
return
if tag in {"del", "s", "strike"}:
self._inline_stack.append("del")
self._emit("")
return
if tag == "code":
self._inline_stack.append("code")
self._emit("")
return
if tag == "br":
self._emit("
")
return
if tag == "ul":
self._li_stack.append("ul")
self._emit("")
return
if tag == "ol":
self._li_stack.append("ol")
self._emit("")
return
if tag == "li":
if self._li_stack and self._li_stack[-1] == "ol":
self._emit('- ')
else:
self._emit("
- ")
return
if tag == "blockquote":
self._blockquote_depth += 1
self._emit("
")
return
if tag == "p":
self._p_depth += 1
self._emit("")
return
if tag == "checkbox":
# Emitted by our preprocessor for GFM task list items.
done = attrd.get("done", "false")
self._emit(f'')
self._inline_stack.append("checkbox")
return
if tag in BLOCK_PASSTHROUGH:
self._emit(f"<{tag}>")
return
# span etc.
if tag == "span":
self._inline_stack.append("span")
self._emit("")
return
# Anything else we don't recognise — drop the tag, keep its text
self._inline_stack.append("__UNKNOWN__")
def handle_endtag(self, tag):
if self._in_pre:
if tag == "code":
self._flush_code()
elif tag == "pre":
self._in_pre = False
return
if self._table_buf is not None:
self._table_buf.append(f"")
if tag == "table":
self._table_depth -= 1
if self._table_depth == 0:
table_xml = "".join(self._table_buf)
self._table_buf = None
# Clean the buffered HTML so it's valid DocxXML
self.out.append(self._sanitise_table(table_xml))
return
if tag == "pre":
self._in_pre = False
return
if tag == "img":
return
if tag == "a":
top = self._inline_stack.pop() if self._inline_stack else None
if top == "__TRANSPARENT_A__":
return
self._emit("
")
return
if tag in {"b", "strong"}:
if self._inline_stack and self._inline_stack[-1] == "b":
self._inline_stack.pop()
self._emit("")
return
if tag in {"em", "i"}:
if self._inline_stack and self._inline_stack[-1] == "em":
self._inline_stack.pop()
self._emit("")
return
if tag in {"u"}:
if self._inline_stack and self._inline_stack[-1] == "u":
self._inline_stack.pop()
self._emit("")
return
if tag in {"del", "s", "strike"}:
if self._inline_stack and self._inline_stack[-1] == "del":
self._inline_stack.pop()
self._emit("")
return
if tag == "code":
if self._inline_stack and self._inline_stack[-1] == "code":
self._inline_stack.pop()
self._emit("")
return
if tag == "span":
if self._inline_stack and self._inline_stack[-1] == "span":
self._inline_stack.pop()
self._emit("")
return
if tag == "ul":
if self._li_stack and self._li_stack[-1] == "ul":
self._li_stack.pop()
self._emit("")
return
if tag == "ol":
if self._li_stack and self._li_stack[-1] == "ol":
self._li_stack.pop()
self._emit("")
return
if tag == "li":
self._emit("")
return
if tag == "blockquote":
self._blockquote_depth = max(0, self._blockquote_depth - 1)
self._emit("")
return
if tag == "p":
self._p_depth = max(0, self._p_depth - 1)
self._emit("")
return
if tag == "checkbox":
if self._inline_stack and self._inline_stack[-1] == "checkbox":
self._inline_stack.pop()
self._emit(" outside we also escape (shouldn't normally happen)
self._emit(xml_escape_text(data))
# ---- code / language extraction ----
@staticmethod
def _extract_lang(class_attr: str) -> str:
# python-markdown fenced_code emits e.g. class="language-mermaid"
for tok in class_attr.split():
if tok.startswith("language-"):
return tok[len("language-"):]
if tok.startswith("lang-"):
return tok[len("lang-"):]
return ""
def _flush_code(self) -> None:
body = "".join(self._code_buf or [])
lang = (self._code_lang or "").strip().lower()
self._code_buf = None
self._code_lang = None
# Mermaid / PlantUML get rendered as whiteboards
if lang in {"mermaid"}:
self._emit(f'{xml_escape_text(body.rstrip())} ')
return
if lang in {"plantuml", "puml"}:
self._emit(f'{xml_escape_text(body.rstrip())} ')
return
# Strip trailing newline that python-markdown adds inside
body = body.rstrip("\n")
lang_attr = f' lang="{xml_escape_attr(lang)}"' if lang else ""
self._emit(f"{xml_escape_text(body)}")
# ---- image emit ----
def _emit_img(self, attrd: dict) -> None:
src = attrd.get("src", "").strip()
alt = attrd.get("alt", "").strip()
title = attrd.get("title", "").strip()
caption = title or alt or None
if not src:
return
if is_http_url(src):
attrs_s = self._attrs_string({"href": src, "caption": caption, "name": alt or None})
self._emit(f"