Wikilinks, Transclusion and Block References

This experiment demonstrates links and embeds that all refer to a small fixture note: a plain link, a custom label, a heading anchor, a whole-note embed, a heading-scoped embed, and a block-reference embed. The sandbox enables wikilink and block-reference parsing in obsidian-flavored-markdown, then uses crawl-links with shortest resolution. The examples below are fenced so that their sandbox-only targets do not become active links in this documentation wiki.

The active link-resolution block is copied verbatim from /home/loca/dev/quartz-sandbox/sandbox/engine/quartz.config.yaml, lines 113–122. In the same file, lines 83 and 87 enable wikilinks and parseBlockReferences respectively.

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

Actual link and embed content, copied contiguously from /home/loca/dev/quartz-sandbox/sandbox/vault/experiments/wikilinks-and-transclusion.md, lines 58–80:

- Bare rooted wikilink: [[experiments/transclusion-source]]
- Aliased label: [[experiments/transclusion-source|a custom label]]
- Heading anchor: [[experiments/transclusion-source#Shared definition]]
- Cross-folder links, resolving upward and downward:
  [[config/index|the config page]], [[plugins/index|the plugin roster]],
  [[index|the sandbox home page]].
 
### Whole-file transclusion
 
![[experiments/transclusion-source]]
 
### Heading-scoped transclusion
 
Only the requested section is pulled in — note that "Not transcluded" does not appear:
 
![[experiments/transclusion-source#Shared definition]]
 
### Block reference
 
The fixture marks one sentence with `^sandbox-block`; embedding that id pulls in exactly
that block:
 
![[experiments/transclusion-source#^sandbox-block]]

The fixture being embedded is not hypothetical. This contiguous excerpt is copied from /home/loca/dev/quartz-sandbox/sandbox/vault/experiments/transclusion-source.md, lines 13–26:

## 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. ^sandbox-block
 
## Not transcluded
 
This last heading exists to prove that a heading-scoped embed pulls in only the requested
section, not the entire file.

What the rendered output proves

Live sandbox page: https://quartz.loca.zone/experiments/wikilinks-and-transclusion.html

Fixture page: https://quartz.loca.zone/experiments/transclusion-source.html

The prior capture in /home/loca/dev/quartz-sandbox/evidence/2026-09-15-quartz-migration-f1fd35c3/sandbox-experiments.json classifies Wikilinks and transclusion with this literal proof_markers object:

{"transclude_class":4}

The experiment’s rendered_proof.routes entry records 46,553 DOM bytes, reading_stats: 2, clipboard_button: 2, and syntax_figures: 2. The fixture route separately records 28,422 DOM bytes and transclude_class: 0. Across the captured routes, all_routes_raw_wikilinks: 0 and all_routes_internal_broken_class: 0 are the recorded output checks. This prior capture used the built release dist-1789511778 through http://127.0.0.1:51963.

These values are receipt marker counters, not counts of actual DOM elements: broad string matches can include quoted source examples. transclude_class: 4 therefore does not mean four rendered transclusion containers or four tested user operations. The receipt also records the absence of its checked unresolved-link markers. The source shows the intended heading and block scopes, but the aggregate marker does not independently prove exact scope exclusion. In particular, the whole-file embed legitimately includes the fixture’s “Not transcluded” heading; a scope test would have to inspect the heading-scoped container rather than demand that text be absent from the entire page. Embedded heading presence does not prove anchor navigation, keyboard focus, or popover interaction. Clipboard-button DOM also does not prove a successful clipboard write.

An independent public-route check on 2026-09-16 fetched https://quartz.loca.zone/experiments/wikilinks-and-transclusion with HTTP 200. Fresh-profile Chrome with a 15-second virtual-time budget exited 0 and returned title Wikilinks, Transclusion and Block References — Quartz Sandbox. Actual class-token counting found three .transclude elements, not four; the historical transclude_class: 4 remains a differently defined marker counter. Two reading-statistics elements carried word/minute pairs 346/2 and 104/1, matching the host article and embedded fixture badges. The DOM was 46,553 bytes, SHA-256 b72f5100ec69cd9c2d6cac618173568dce3c8380d1a71fab503b07c8529f4c30. No anchor click or scoped-content exclusion was exercised by this capture.

Safe for the shared engine?

Recorded assessment: safe_for_shared_engine: true.

Receipt reason, verbatim:

Shortest resolution and transclusion are existing behavior; disableBrokenWikilinks changes no routes.

A true verdict does not authorize a shared-engine change. Any requirement to modify /home/loca/dev/quartz/quartz must be reported as a BLOCKER, not performed as an action. This is a recorded compatibility assessment, not permission to change the engine shared by 51 wikis.

Try it in the sandbox

After editing only authorized sandbox content or configuration, rebuild through the isolated wrapper:

cd /home/loca/dev/quartz-sandbox/sandbox && ./build.sh

The wrapper /home/loca/dev/quartz-sandbox/sandbox/build.sh pins the isolated engine to commit 3dff48b5df6d84c9544a5ae19c8f2cbb01dc44e5 and takes a nonblocking .build.lock; a competing build is rejected instead of overlapping. It runs install-plugins before bootstrap-cli.mjs build, with --directory pointing to /home/loca/dev/quartz-sandbox/sandbox/vault and --output pointing to a new timestamped /home/loca/dev/quartz-sandbox/sandbox/dist-<timestamp> directory. It checks for index.html before atomically replacing current. The origin sees the new release on the next request without a restart.

Recorded runtime invocation from sandbox-runtime.json, reference only:

PATH=/usr/bin:/bin PORT=51947 SANDBOX_ROOT=/home/loca/dev/quartz-sandbox/sandbox/current NODE_ENV=production /usr/bin/node /home/loca/dev/quartz-sandbox/sandbox/serve.mjs

The production service already owns port 51947. Do not start a second process or restart the service. The runtime receipt records an earlier supervised process and release-swap proof; it is not a second launch instruction. No sandbox rebuild or service change was performed to author this documentation.

index