1 min read

pyssg.plugins.highlight

Syntax-highlighting plugin: colourise fenced code via Pygments.

Runs in the parse phase at stage 250, i.e. after the markdown plugin (stage 200) has rendered node.meta["content_html"] and the verbatim copy node.meta["__content_html_raw__"] that downstream link rewriting reads, and after an optional mermaid plugin (stage 230) which converts mermaid fences into <pre class="mermaid"> blocks that no longer match the <pre><code> markup this plugin rewrites -- so mermaid diagrams are skipped naturally.

This plugin only transforms already-rendered HTML in place: it reads the two content_html keys, replaces every code block with Pygments output, and writes them back. It owns no graph algorithm or cache state (plugins declare facts, the engine owns invalidation). cache_version folds in the style name so switching themes busts the render cache.

Every computation is pure: it depends solely on the rendered HTML and the chosen style, never on a clock or randomness, so two builds of the same input are byte-identical.

pygments is third-party. It is allowed in a peripheral plugin like this one, but never in pyssg.core.

highlight_html(html_text: str, highlighter: HtmlFormatter) -> str

Replace every <pre><code> block in html_text with Pygments output.

For each matched block: recover the source by html.unescape-ing the escaped body, pick a lexer from the language-LANG class (TextLexer when the language is missing or unknown), and render it with the shared highlighter. mermaid fences are left verbatim so a mermaid plugin can claim them. HTML that does not match the code-block markup is untouched.

class HighlightPlugin

Colourises fenced code blocks in rendered Markdown HTML via Pygments.

HighlightPlugin.__init__(self, style: str = 'default') -> None

HighlightPlugin.apply(self, builder: Builder) -> None

highlight(style: str = 'default') -> HighlightPlugin

Factory used in pyssg.config.py.