title: Passthrough files

Passthrough files

Audio, video, PDFs, EPUBs — files the build doesn't render but ships to the deploy alongside the wiki. They follow the same per-variant gating contract as images: a file lands in a deploy variant only if a visible page in that variant references it.

Recognised extensions

Anything else is treated as unknown — see the bottom of this page.

How references are detected

Three patterns count as a reference. As long as a visible page in the target variant matches one, the file ships to that variant:

![[file.ogg]]                  # Obsidian embed (audio plays inline)
[[file.ogg]]                   # Obsidian wikilink
[label](path/to/file.pdf)      # standard markdown link

If you want an audio file gated to the DM tier, just reference it from a DM-only page (or a DM-only callout). The build does the rest.

Live demo: this audio cue

This page links to tavern-jingle.ogg — a short 17 KB OGG. Because this page is public (no role: frontmatter override), the file ships to all three deploy variants. View /Audio/tavern-jingle.ogg directly: it loads.

Verifying the gating

# Build the vault to a temp dir
vaults build --output /tmp/out

# At each tier, only the audio referenced by visible pages should appear.
ls /tmp/out/_variants/public/Audio/
ls /tmp/out/_variants/patron/Audio/
ls /tmp/out/_variants/dm/Audio/

If you wrap an audio embed inside a > [!dm] callout in an otherwise-public page, the callout AND the file disappear from the public/patron variants — the page renders without them, and the file structurally doesn't ship.

Unknown extensions

Anything outside the recognised list is dropped from the deploy by default, with a warning at build time:

  skipping 1 file(s) with unrecognized extensions:
    handouts/data.bin
    Set 'include_unknown_files: true' in settings.md to ship them.

This is a safety default: a stray file in your vault can't accidentally bypass role gating. To opt in, add this to settings.md:

include_unknown_files: true

When enabled, unknown-extension files join the passthrough pool — they still need to be referenced by a visible page (in the target variant) to ship. The role gating contract isn't relaxed; only the recognition gate is.

What about HTTP-referenced files?

<a href="/audio/foo.ogg"> and similar raw-HTML references are NOT detected by the scanner — only markdown-level patterns are. If you need to reference a file from raw HTML, also add a markdown-level reference elsewhere on the page (or inside a comment):

<!-- ![[foo.ogg]] -->
<a href="/Audio/foo.ogg">play me</a>

The HTML comment ensures the file is shipped without affecting the rendered output.