MathJax

2026-05-01T00:00:00+00:00

Halcyon has built-in support for MathJax, which allows you to include mathematical notation in your content using LaTeX syntax. I personally heavily use math notation in Obsidian, so I wanted to make sure that this feature was supported in Halcyon as well.

The Sad</a></h2>

Zola does not have support for MathJax on generation side of things. So we have to "patch" the HTML directly, or write some sort of preprocessor that is completely separate from the zola</code> binary. For now, I've opted for the former, but eventually I'd like to have some form of preprocessor, either Rust based or JS based, that we can use to preprocess before Zola does its thing.

The Good</a></h2> Client-side MathJax support isn't necessarily hard to add to a site. You have to include the MathJax script through CDN in your <head></code>, and have an accompanying script that does configuration. For the Halcyon theme, the configuration is done in static/js/mathjax.js</code>. See the mathjax documentation</a> on how this configuration works. The interesting part is that we have to do some work to ensure that math is properly rendered when \\</code> is used, which Zola interprets as an escaped backslash. Clearly, directly passing that to e.g. \begin{align}</code> or simimlar won't work, as we expect \\</code> there for linebreaks! To fix this, we need to replace all instances of \</code> in the HTML with \\</code>, but only for math content. The mathjax configuration allows me to call a function before math is rendered. Said function -- fixCollapsedNewlines</code> -- uses a TreeWalker</code></a> to get text nodes in the page, ignoring when the parent node is e.g. <script></code> or <code></code>, and ignoring if the text node doesn't include $$</code> -- which is the syntax for math. The nodes left over are indeed math equations, and we can safely replace \</code> with \\</code> in those nodes. $$ \begin{align*} E &= m\cdot c^2 \ m \cdot c^2 &= E \end{align*} $$ As can be seen, the above renders, so our replacement works. It's done with the functions below (comments stripped to save space, but you can see the full code in static/js/mathjax.js</code>): 1 const normalizeDisplayMathLine = (line, index, lines) => { 2 if (index === lines.length - 1) { 3 return line; 4 } 5 6 return /(^|[^\\])\\\s*$/.test(line) 7 ? line.replace(/\\(\s*)$/, String.raw`\\$1`) 8 : line; 9 }; 10 11 const normalizeDisplayMathBlock = (inner) => inner 12 .replaceAll("\r\n", "\n") 13 .split("\n") 14 .map((l, i, ls) => normalizeDisplayMathLine(l, i, ls)) 15 .join("\n"); 16 17 const normalizeDisplayMathText = (text) => text.replaceAll(/\$\$([\s\S]*?)\$\$/g, (_match, inner) => { 18 const normalizedInner = normalizeDisplayMathBlock(inner); 19 return `$$${normalizedInner}$$`; 20 });</code></pre> The equation shown above is made with the following notation: $$ \begin{align*} E &= m\cdot c^2 \\ m \cdot c^2 &= E \end{align*} $$</code></pre></blockquote>

Diagramming with Mermaid 2026-05-01T00:00:00+00:00 Halcyon has built-in support for Mermaid, which allows you to include diagrams in your content using Mermaid syntax. This is yet another feature to get parity with Obsidian. The Bad</a></h2> Like [[features/mathjax|mathjax]], Zola does not have support for MathJax on generation side of things. So we have the same choice to either "patch" the HTML directly, or write some sort of preprocessor that is completely separate from the zola</code> binary. Even if Zola did have support for Mermaid, Mermaid itself doesn't have support for dark-light theming, so we'd still have to do some effort to make things work. The Bug!</a></h2> Right now, there's a slight issue with how things work (see below). Because mermaid has no notions of theme switching on-the-fly, by switching themes we have to rerender the entire diagram, which resets the scroll position. This is a known issue, and should be fixed in a future release of the Halcyon theme. The .. yeah, no word starting with B here</a></h2> Including Mermaid is done with a script tag in the <head></code>, and then we have an accompanying script that looks for code blocks with mermaid</code> as the language, and transforms them into Mermaid diagrams. Because of the aforementioned issue with theme switching, we also have to listen for theme changes, and re-render the diagrams when that happens. graph TD A[Code block with mermaid] --> B[JS looks for code blocks with mermaid language] B --> C[JS transforms code block into Mermaid diagram] D[User switches theme] --> E[JS listens for theme change event] E --> F[JS re-renders Mermaid diagrams to apply new theme]</code></pre> The above diagram is made using following mermaid codeblock: graph TD A[Code block with mermaid] --> B[JS looks for code blocks with mermaid language] B --> C[JS transforms code block into Mermaid diagram] D[User switches theme] --> E[JS listens for theme change event] E --> F[JS re-renders Mermaid diagrams to apply new theme]</code></pre> Table of Contents 2026-05-01T00:00:00+00:00 From Typora days I've become accustomed to generating a table of contents with [TOC]</code> syntax. This is a feature that Zola doesn't have built-in support for, but it's easy enough to add since Zola does keep track of the actual headings in the page. [TOC] Even if the [TOC] string is placed inline here, it is shown on the top of the page. And, as you can see, including it a second time as I've done, doesn't generate a second one or errors out. Below are some unused headers so you can see how everything works. Hello World</a></h2> Headers are nice</a></h2> We can do subheaders too</a></h3> This one is too deep, so isn't shown!</a></h4> This one will be shown again</a></h3> You can use code</code> in headers</a></h2> This gets rendered in the page, and not in the TOC, as one would expect. And if you really want to, $math$ too</a></h2> It gets rendered in the page, and the TOC. I should change this so it's only in the page, probably. But who is using math in headers? Icons</a></h2> Technically work, but not in TOC. This uses the icon shortcode! Before links</a> is fine but after ...</a></h2> links</code> in the header above is a distinct link. You shouldn't put links in headers -- it will break things. Wikilinks 2026-04-27T00:00:00+00:00 If you happen to use Obsidian, you'll be very familiar with [[wikilinks]]</code>. This feature is a DIY implementation that, client-side, transforms raw [[link]]</code> into <a></code> tags. It's very bad for SEO, and I don't necessarily recommend using it. But it's there, for the period of time that Zola doesn't yet have official wikilink support. The Details</a></h2> The implementation for wikilinks lives in static/js/wikilinks.js</code>. It works as follows: For each node in the DOM, if it's a text</code> node and its parent is not a script</code>, style</code>, code</code>, pre</code>, or textarea</code> element, do:</li> Check for a match with a wikilink regex pattern.</li> If we match, construct a document fragment, where we replace the wikilink syntax with an anchor tag. The URL of the anchor tag is generated by a simple slugification of the page name, and the display text is either the page name or the custom display text if provided.</li> Replace the original text node with the constructed document fragment.</li> </ol> The interesting part of the implementation is shown below, where we convert a page name, e.g. chicken</code> for [[chicken]]</code>, into a URL, e.g. /chicken/</code>. The slugification process is very basic, and simply lowercases the page name, trims whitespace, and replaces spaces with dashes. There are also special cases for home</code> (which links to the root) and for in-page anchors (which start with #</code>). 1 const pageNameToUrl = (pageName) => { 2 const slug = pageName 3 .toLowerCase() 4 .trim() 5 .replaceAll(/\s+/g, '-'); 6 7 // Special case: "home" links to root 8 if (slug === 'home') { 9 return '/'; 10 } 11 12 // Special case: #some-header links to in-page anchor 13 if (slug.startsWith('#')) { 14 const currentPage = globalThis.location.pathname.replace(/\/?$/, '/'); // Ensure trailing slash 15 return currentPage + slug; 16 } 17 18 // Ensure leading slash, trailing slash 19 const url = '/' + slug.replaceAll(/^\/+|\/+$/g, '') + '/'; 20 // Ensure we respect the base URL 21 const base = document.querySelector('base')?.getAttribute('href') || '/'; 22 return base + url; 23 };</code></pre> Go back to read [[#The Details]] (made with wikilink syntax, e.g. [[#The Details]]</code>) or alternatively The Details</a> with regular anchor link syntax.

</i> Icons</a></h2>
Technically work, but not in TOC. This uses the icon shortcode!</p>
Before links</a> is fine but after ...</a></h2>
`links</code> in the header above is a distinct link. You shouldn't put links in headers -- it will break things.</p>`

Before links</a> is fine but after ...</a></h2>
`links</code> in the header above is a distinct link. You shouldn't put links in headers -- it will break things.</p>`

MathJax

Diagramming with Mermaid

Table of Contents

Wikilinks