"""Markdown rendering.
Raw HTML (including inline scripts) is passed through unfiltered: the
single author is trusted. Extensions: tables and strikethrough (from the
"default" preset), footnotes, definition lists, task lists,
brace-attributes (`{.class width=300}` on any element, images in
particular), admonitions (``!!! note Title`` with an indented body —
note/tip/warning/etc., the title optional) and GitHub-style alerts
(``> [!NOTE]`` / TIP / IMPORTANT / WARNING / CAUTION, rendered in the
same callout styling). ``::: name`` opens a generic container rendered
as ``
`` and closed by a matching ``:::`` (nest by
giving the outer container more colons, e.g. `::::`); the name may be
followed by brace attributes (``::: aside {.right}``), or omitted for a
pandoc-style nameless div (``::: {.aside}``). ``::: aside``
floats as a muted side box, floating in the side zone at the article's
left on all but phone widths — the same margin float ``{.margin}`` (or
``::: margin``) gives any block — and ``::: nocols`` opts its section out
of the column layout. A brace-attribute
line as a block's last line (no blank line between) applies to the whole
block, e.g. a paragraph ending with ``{.wide}`` breaks out of the column
layout as a full-width element; written after a block (code fence,
heading, container, ...) it applies to that preceding block. Bare URLs autolink (GFM), with
the ``https://`` scheme hidden in the link text (``http://`` and other
schemes stay visible; manually labelled links are untouched), and
``H~2~O`` / ``x^2^`` give sub/superscripts.
render() also builds the layout structure: the top-level blocks are
segmented for the column layout — h1/h2 headings and ``.wide`` blocks
stand on their own, the runs between them are wrapped in
``
wrapper,
and the stylesheet is scoped to "pre code" to match.
"""
try:
lexer = get_lexer_by_name(lang)
except ClassNotFound:
return "" # fall back to default
return highlight(text, lexer, _formatter)
def _fence_rule(
self: RendererHTML,
tokens,
idx: int,
options,
env: dict,
) -> str:
"""Render a fenced code block.
Like the default fence rule, but block attributes go on the
—
the block element — instead of the , which keeps only the
language class. Attributes are accepted both pandoc-style on the
info line (```{.python .wide #id key=val} — the first class is the
language when no bare language word precedes the braces) and as a
trailing `{...}` line applied by _block_attrs. This is what makes
e.g. `{.wide}` or `{style="..."}` style the block itself.
"""
token = tokens[idx]
info = token.info.strip() if token.info else ""
lang, _, brace = info.partition("{")
lang = lang.split(maxsplit=1)[0] if lang.strip() else ""
if brace:
try:
_, attrs = parse_attrs("{" + brace)
except ParseError:
attrs = {}
classes = attrs.pop("class", "").split()
if not lang and classes:
lang = classes.pop(0)
if classes:
_apply_attrs(token, {"class": " ".join(classes)})
_apply_attrs(token, attrs)
highlighted = _highlight(token.content, lang, "") or escapeHtml(token.content)
code_class = f' class="{options.langPrefix}{lang}"' if lang else ""
return (
f"{highlighted}
\n"
)
def _image_rule(
self: RendererHTML,
tokens,
idx: int,
options,
env: dict,
) -> str:
"""Render images, resolving relative srcs against the page path."""
token = tokens[idx]
src = token.attrs["src"]
if not src.startswith(("/", "http://", "https://", "data:")):
page = env.get("page_path", "")
token.attrs["src"] = f"/{page}/{src}" if page else f"/{src}"
token.attrs["alt"] = self.renderInlineAsText(token.children, options, env)
if len(tokens) == 1:
# The only inline content of its paragraph: render as a block
# figure, captioned when titled. (The
wrapper is dropped by
# _unwrap_lone_figures below.) {.margin} positions the whole
# figure, so it moves from the img onto the figure wrapper — left
# on the img, the margin-breakout CSS would pull the image out of
# the figure (and mostly off-screen), leaving the caption behind.
classes = (token.attrs.get("class") or "").split()
figure_class = ""
if "margin" in classes:
classes.remove("margin")
if classes:
token.attrs["class"] = " ".join(classes)
else:
del token.attrs["class"]
figure_class = ' class="margin"'
img = self.renderToken(tokens, idx, options, env)
title = token.attrs.get("title")
caption = f"{escapeHtml(title)}" if title else ""
return f"{img}{caption}
"
img = self.renderToken(tokens, idx, options, env)
# Inline with other content: a plain inline image.
return img
def _unwrap_lone_figures(state) -> None:
"""Drop the
wrapper around a lone image.
markdown-it wraps inline content in a paragraph, but our image rule
turns lone images into — a block element that is invalid
inside
", re.DOTALL)
# Classes that take their block out of the column flow: .wide is a
# full-width separator that splits the column segments. Margin-breakout
# boxes (.margin/.aside) are NOT boundaries: they stay inside the segment
# at their anchor point, and CSS positions them absolutely out of the
# article's left border (the zone rules anchor off the article), so the
# column flow is unaffected.
_WIDE = "wide"
class Rendered(NamedTuple):
"""render() result: the segmented body HTML, and whether the article
should carry .multicol (enough visible text to justify columns)."""
html: str
multicol: bool
def _classes(token) -> set[str]:
return set((token.attrGet("class") or "").split())
def _text_len(html: str) -> int:
"""Visible-text length of rendered HTML, code blocks excluded."""
return len(_TAG_RE.sub("", _PRE_BLOCK_RE.sub("", html)).strip())
def _breakable_paras(html: str) -> str:
"""Mark column-filling paragraphs .breakable so they may split.
Columns keep paragraphs whole (break-inside: avoid-column), but a
paragraph long enough to fill a column would strand everything after
it in a column of its own — these get .breakable, and pagerite.css
lets them split across the column gap. Only applied to .cols segments.
"""
def repl(m: re.Match[str]) -> str:
attrs, body = m.group(1), m.group(2)
if _text_len(body) <= BREAKABLE_TEXT:
return m.group(0)
if 'class="' in attrs:
attrs = attrs.replace('class="', 'class="breakable ', 1)
else:
attrs = f'{attrs} class="breakable"'
return f"{body}
"
return _PARA_RE.sub(repl, html)
def _top_level_blocks(tokens: list) -> list[list]:
"""Split the token stream into its top-level blocks.
A new block starts at each level-0 opening/self-contained token;
closing and nested tokens (inline children, sub-containers) belong to
the current block, so every slice is balanced and renders on its own.
"""
blocks = []
for token in tokens:
if token.level == 0 and token.nesting >= 0:
blocks.append([token])
elif blocks:
blocks[-1].append(token)
return blocks
def _is_boundary(block: list) -> bool:
"""True for blocks that never go inside a column segment (see the
_WIDE comment above): h1/h2 headings and anything carrying .wide."""
first = block[0]
if first.type == "heading_open" and first.tag in ("h1", "h2"):
return True
for token in block:
if _WIDE in _classes(token):
return True
if token.type == "inline":
children = token.children or []
if any(_WIDE in _classes(c) for c in children):
return True
return False
def render(
text: str,
page_path: str = "",
created: datetime | None = None,
modified: datetime | None = None,
title: str | None = None,
anchors_from: tuple[str, str] | None = None,
directives: dict[str, Callable[[str, dict], str | None]] | None = None,
) -> Rendered:
"""Render Markdown text to the article body's HTML and layout flags.
``title`` injects a ``# {title}`` line at the top when the markdown has
no h1 of its own, so the implicit page title goes through the exact
same pipeline as an explicit one (first-h1 anchor treatment included).
``anchors_from`` is the (markdown, title) of the ORIGINAL language when
rendering a translation: section anchors are pinned to its slugs so
localized pages keep the original #hash URLs.
The top-level blocks are grouped into column segments: boundary blocks
(h1/h2 headings, .wide — see _is_boundary) are rendered bare, the runs
between them wrapped in
.
A segment is tagged .cols when it holds enough text (COLS_TEXT) in at
least two paragraphs (COLS_PARAS) or one breakable-length paragraph,
and no ::: nocols container; its long paragraphs are marked .breakable;
the article is .multicol when the whole body exceeds MULTICOL_TEXT.
pagerite.css keys all column and margin-breakout layout off these
classes.
A ``{dates}`` line expands to the article's published/updated dateline
(needs ``created``/``modified``). Block directives in general — a lone
``{name}`` or ``{name: args}`` line — are expanded by the resolvers
passed as ``directives`` (name → (args, env) → HTML or None), with
``dates`` built in when ``created`` is given; unresolved tags render as
the literal source (e.g. in the editor preview of a not-yet-created
page).
Position is the author's choice — the dateline typically goes
right after the article's h1.
"""
directives = dict(directives or {})
if created is not None:
directives.setdefault("dates", lambda _args, _env: _dateline(created, modified))
env = {"page_path": page_path, "line_offset": 0, "directives": directives}
if anchors_from is not None:
env["anchor_ids"] = anchor_ids(*anchors_from)
if title and not has_h1(text):
text = f"# {title}\n\n{text}"
# The injected title shifts source lines by two; _heading_ids
# subtracts this from its data-line attributes.
env["line_offset"] = 2
blocks = _top_level_blocks(md.parse(text, env))
# Group consecutive non-boundary blocks into segments (is_segment,
# flat tokens); boundary blocks stand on their own between them.
groups: list[tuple[bool, list]] = []
for block in blocks:
if _is_boundary(block):
groups.append((False, block))
elif groups and groups[-1][0]:
groups[-1][1].extend(block)
else:
groups.append((True, list(block)))
parts = []
total = 0
for is_segment, group in groups:
html = md.renderer.render(group, md.options, env)
if not html.strip():
continue # e.g. a consumed standalone-attrs paragraph
text_len = _text_len(html)
total += text_len
if not is_segment:
parts.append(html)
continue
nocols = any(
"nocols" in _classes(t) for t in group if t.type == "container_block_open"
)
marked = _breakable_paras(html)
cols = (
" cols"
if text_len > COLS_TEXT
and not nocols
and (len(_PARA_OPEN_RE.findall(html)) >= COLS_PARAS or marked != html)
else ""
)
if cols:
html = marked
parts.append(f'
{html}
')
html = "".join(parts)
return Rendered(html, total > MULTICOL_TEXT)
def _dateline(created: datetime, modified: datetime | None) -> str:
"""Dateline for the ``{dates}`` tag: "1 Jan 2026", plus
" – edited 3 Jan 2026" when the last edit came >= 48h after
publishing (quick fixes right after posting stay unmentioned)."""
out = f''
if modified is not None and modified - created >= timedelta(hours=48):
out += f' – edited '
return f'
{out}
'
def has_h1(text: str) -> bool:
"""True if the Markdown source itself contains an h1 heading.
When it does, the article owns its heading and render(title=...) does
not inject the page title as an h1 (the title is still used for the
document and navigation labels).
"""
return any(t.type == "heading_open" and t.tag == "h1" for t in md.parse(text))
def toggle_task(text: str, index: int) -> str | None:
"""Toggle the Nth task-list checkbox marker in ``text``.
Returns the modified Markdown source, or ``None`` if the index is out
of range or the marker could not be found.
"""
tokens = md.parse(text, {"page_path": ""})
checkbox_lines: list[int | None] = []
for token in tokens:
if token.type == "inline" and token.children:
for child in token.children:
if child.type == "html_inline" and 'type="checkbox"' in child.content:
checkbox_lines.append(token.map[0] if token.map else None)
break
if not (0 <= index < len(checkbox_lines)):
return None
line_idx = checkbox_lines[index]
if line_idx is None or line_idx < 0:
return None
lines = text.splitlines(keepends=True)
if line_idx >= len(lines):
return None
line = lines[line_idx]
def repl(m: re.Match[str]) -> str:
prefix = m.group(1)
marker = m.group(2)
new_marker = "x" if marker.strip() == "" else " "
return f"{prefix}[{new_marker}]{m.group(3)}"
new_line = _TASK_MARKER_RE.sub(repl, line, count=1)
if new_line == line:
return None
lines[line_idx] = new_line
return "".join(lines)