2.3 – Markdown snippets

If file ends in .md, the file is turned into HTML at build time. What is rendered is GitHub-Flavored Markdown, embedded HTML is allowed, and placeholders work as they do elsewhere:

## {{siteTitle}}
 
Notes from a _small_ town.
 
- <a href="{{root}}/about">About this site</a>
- <a href="{{root}}/contact">Contact</a>

The box at the bottom left of this site is made exactly that way — with Markdown links, ever since the plugin learned to recognise the encoded form. Why that did not work for a while, and when an HTML anchor is still the safer way, is right below.

What does not work there

A Markdown snippet does not go through Quartz’ content pipeline. What stays as written:

Written	What becomes of it
[[wikilink]]	stays as text
> [!note]	becomes an ordinary quote, not a callout
![[image.png]]	stays as text
[text](target)	becomes a link — ordinary Markdown works
[text]({{root}}/target)	becomes a link with the value filled in — see below
**bold**, lists, tables, headings	all work

The reason is in 1.3: the plugin is a pure component. It is asked when Quartz builds the layout — and by then the content has long been processed.

A placeholder in a link target — the story behind it

That the line above works has not been true for long, and the reason is worth knowing.

Markdown is rendered to HTML first, placeholders are replaced afterwards (1.3). While rendering, the Markdown renderer turns a link target into an address and escapes the curly braces to %7B%7B and %7D%7D. The replacement then looked for {{root}} and found nothing; the HTML literally said %7B%7Broot%7D%7D.

Inside the href of an HTML element that never happened — there the address stays as it is until the replacement reaches it. Two spellings that look equivalent in the source behaved differently.

Fixed, but not retroactively

The plugin now recognises the encoded form and treats both spellings alike. Anyone on an older version writes links in a snippet as HTML anchors: <a href="{{root}}/about">About this site</a>. That works in every version.

Only found on publishing

As long as a site sits at the root, a broken path barely shows. Under a subpath — the normal case on GitHub Pages — every one of those links led nowhere. That is exactly how it came out: on the first deploy of these four sites, 14 dead links at once.

Links in a snippet want {{root}}

A snippet appears on every page, including those two levels down. A link to /about misses the server root as soon as the site lives under a subpath. {{root}}/about works the way out from every page; see 4.2 – root and addresses.

HTML or Markdown?

Markdown pays off as soon as the snippet holds prose, a list or links — it is shorter and reads better while editing. HTML pays off as soon as structure is involved that Markdown does not know: an <svg>, an image with a light and a dark variant, an element with a class of its own.