Embeds

Embeds

An embed is a standalone Markdown image link — ![alt](src) on its own line — that track renders as rich media instead of a plain <img>. Inline image syntax inside a paragraph stays inline, so embedding is always opt-in and ordinary [text](url) links are never turned into noisy previews. track routes each embed by the kind of target (below); only http(s) and relative URLs feed an iframe, so a note cannot smuggle a javascript: document into an embed.

See also Diagrams and Charts.

Local files

Local media belongs under the vault's assets/ directory. track asset import ./image.png copies the file there and prints the relative reference you can paste into a note:

![track logo](assets/logo.png)

A relative assets/<file> reference is served from the vault by the local server, so it is never treated as a YouTube/tweet/OGP URL.

Image captions

Add a Markdown title after an image path to show a small caption below the image:

![track logo](assets/logo.png "The track logo")

The track logo

The alt text (track logo) remains the image's accessible description; it is not used as a caption. Missing, empty, or whitespace-only titles add no caption. Titles display as plain text, including characters such as & and <, without interpreting HTML or Markdown. Captions also appear in image previews, the enlarge lightbox, and published notes. Titles on other embed kinds (videos, PDFs, diagrams, and web-page cards) do not add captions.

YouTube

A YouTube watch, share, or embed URL becomes an inline player:

![Intro](https://www.youtube.com/watch?v=aqz-KE-bpKQ)

Google Maps

A Google Maps share or embed URL becomes an inline map. Paste the Share → Embed a map URL as-is, or build the keyless form yourself with a query or coordinates — no API key is needed. Short maps.app.goo.gl links need a network redirect to resolve, so those fall back to an Open Graph card instead:

![都庁](https://maps.google.com/maps?q=35.6896,139.6917&z=16&output=embed)

This one is live — it centers on the Tokyo Metropolitan Government building (都庁):

Twitter / X

A tweet URL renders the actual post via Twitter's official widgets (matching how Obsidian embeds tweets), not just a link card. While the widget loads it shows a plain link, and if the post cannot be rendered — deleted, blocked, or offline — it falls back to the generic Open Graph card:

![](https://x.com/elonmusk/status/1585341984679469056?s=20)

PDF

A PDF (local asset or remote URL) opens in a paged slide-deck viewer rather than a download link:

![Deck](assets/slides.pdf)

This one is live — page through it with the arrows (or click a page). The sample is a three-page deck with just the page number on each page:

Web pages (Open Graph)

Any other http(s) page becomes an Open Graph card — its title, description, and preview image pulled from the page's og: metadata:

![](https://example.com/article)

Text-file attachments

A text file imported with track asset import is fetched and rendered inline instead of shown as a broken image. A config file, script, or data snippet you want to keep beside a note (.txt, .json, .yaml, .csv, .sh, …) renders as a syntax-highlighted code block:

![](assets/pod.yaml)

Two text kinds render as something richer instead: a diagram source (.mmd / .mermaid for Mermaid, .dot / .gv for Graphviz, .d2 for D2, .c4 / .likec4 for LikeC4, .drawio for draw.io) becomes a diagram — see Diagrams — and a .viewspec.json becomes a chart — see Charts.

HTML pages

An HTML file is a vault asset like any other: track asset import ./demo.html copies it under assets/, and the standard embed syntax mounts it in a sandboxed iframe — its own JS and CSS run, but it is isolated from the workspace (unique opaque origin, no access to the app, cookies, or storage):

For a full-page browser app with relative files, use Static apps instead. A static app opens as a top-level page with no iframe or sandbox; this assets/ embed stays inside the note and sandboxed.

![Demo](assets/demo.html)

A remote http(s)://…/page.html URL is not mounted this way: it becomes an Open Graph card like any other web page rather than a sandboxed iframe — see Web pages (Open Graph) above. On a published site that card is fetched from the reader's browser rather than the local /api/ogp proxy, so the reader still connects to the remote host — one metadata request (which a cross-origin refusal degrades to a bare link) instead of a fully rendered, scripted page. The iframe has a fixed default height since a raw HTML page has no intrinsic aspect ratio, but you can set it with a :height option after the embed — the same Org-style :key value tail Babel and note includes use:

![Demo](assets/demo.html) :height 480
![Map](assets/map.html) :height 90%

A bare number is pixels; a % or vh value is a share of the viewport height.

Use :frame none when the embedded page should sit directly on the note without the visible frame:

![Demo](assets/demo.html) :frame none

This changes only the border, rounded corners, and clipping around the iframe. The sandbox stays in place, so the page still runs with allow-scripts allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals and allow="clipboard-write", and no allow-same-origin.

A link opened from the embedded page comes up as an ordinary tab rather than a sandboxed one, and the frame grants the embedded page clipboard-write permission.

The sandbox has no allow-forms, and a blocked submission never dispatches the submit event — so an embedded page that relies on <form> submit semantics silently does nothing. Drive actions from JavaScript click handlers (<button type="button">) and window.open instead; an Enter-key shortcut needs its own keydown listener.

The Web workspace renders every embed live; the static export (CLI export-site) renders the same output for a published note.

Draw.io attachments, including .drawio, .drawio.svg, and .drawio.png, are read-only in Track. To edit a diagram in the workspace, paste its source XML into an unindented drawio fence in the note body and use Edit draw.io diagram. See Web workspace#Editing draw.io diagrams.