346 words · 2 min read · Sandbox reading stats

Wikilinks, transclusion and block references

What this demonstrates

Two plugins co-operate here. obsidian-flavored-markdown parses [ [ and ] ] notation into links and embeds; crawl-links then resolves each one against the site’s slug set using the configured strategy and rewrites the href to a correct relative path.

This sandbox also turns on a link-validity gate: with disableBrokenWikilinks: true, any internal link whose resolved slug does not exist in the build gains an extra broken class. That converts “did I typo a wikilink?” from a proofreading problem into a greppable assertion over the emitted HTML — the sandbox’s rendered-proof step requires zero unresolved internal-anchor classes across every page.

Configuration used

  - source: "@quartz-community/crawl-links"
    enabled: true
    options:
      markdownLinkResolution: shortest
      disableBrokenWikilinks: true
      externalLinkIcon: true
      lazyLoad: true
    order: 60

Under shortest, a link with no slash is matched by filename anywhere in the vault, and a link containing slashes is treated as a path from the vault root. Every wikilink in this vault is written in the rooted form ([ [experiments/transclusion-source] ]) so that adding a same-named file elsewhere later cannot silently re-point it.

Content used

[ [experiments/transclusion-source] ]
[ [experiments/transclusion-source|a custom label] ]
[ [experiments/transclusion-source#Shared definition] ]
 
! [ [experiments/transclusion-source] ]
! [ [experiments/transclusion-source#Shared definition] ]
! [ [experiments/transclusion-source#^sandbox-block] ]

Rendered result

Plain links

• Bare rooted wikilink: transclusion-source
• Aliased label: a custom label
• Heading anchor: experiments/transclusion-source > Shared definition
• Cross-folder links, resolving upward and downward: the config page, the plugin roster, the sandbox home page.

Whole-file transclusion

Transclusion Source

104 words · 1 min read · Sandbox reading stats

This note is a fixture. The transclusion experiment embeds it three different ways, so the text below is deliberately short and identifiable in rendered HTML.

Shared definition

A transclusion is a reference that renders the referenced content in place, rather than linking away to it. Quartz resolves transclusions at build time, so the embedded HTML is present in the emitted page and needs no JavaScript to appear.

Block reference target

This sentence is the block-reference target for the transclusion experiment.

Not transcluded

This last heading exists to prove that a heading-scoped embed pulls in only the requested section, not the entire file.

Link to original

Heading-scoped transclusion

Only the requested section is pulled in — note that “Not transcluded” does not appear:

Shared definition

A transclusion is a reference that renders the referenced content in place, rather than linking away to it. Quartz resolves transclusions at build time, so the embedded HTML is present in the emitted page and needs no JavaScript to appear.

Link to original

Block reference

The fixture marks one sentence with ^sandbox-block; embedding that id pulls in exactly that block:

This sentence is the block-reference target for the transclusion experiment.

Link to original

What the rendered output proves

The emitted HTML contains class="internal" anchors with rewritten relative hrefs, class="transclude" containers holding the fixture’s real text (so the embed happened at build time, not via a client fetch), and zero unresolved internal-anchor classes — the gate above. The heading-scoped case contains the fixture’s “A transclusion is a reference…” sentence while omitting its “Not transcluded” section, proving the scope is honoured rather than the whole file being inlined.

safe_for_shared_engine

true — shortest resolution and transclusion are existing engine behaviour; the only sandbox-specific addition is disableBrokenWikilinks, which adds a CSS class and changes no routes.