Docs
Obsidian Embed Policy
How Learning Lab notes use wiki links and embeds for short reusable reference material.
Status: Working policy for source notes and intranet rendering.
The Learning Lab source is meant to stay comfortable for people writing in Obsidian. That means wiki links and short embeds are allowed, but they have a narrow job.
Link vs Embed
Use [[...]] when the reader should go to another note.
Use ![[...]] when the same short reference language should appear inside the current note.
Embeds are for canonical blurbs that need to stay consistent across modules and labs: definitions, disclaimers, safety language, standard warnings, and short review reminders.
For glossary definitions, keep the definition in the term note and embed only the ## Definition section. Do not split every definition into a separate file.
Allowed Embed Sources
Embeds should come primarily from learning-library/.
Good embed candidates:
- glossary definitions
- short safety disclaimers
- standard review language
- brief consistency blurbs
- short checklist sections
Prefer links for:
- full modules
- track notes
- long cheatsheets
- facilitator guides
- anything that turns the current page into a stitched-together lesson
Supported Forms
The intranet renderer supports:
[[friction]][[friction|Friction]]![[friction]]![[friction|Friction]]![[friction#Definition]]![[friction#Definition|Friction Definition]]
For glossary terms, prefer:
![[friction#Definition]]
That renders the term name plus only the definition section.
Authoring Rules
Keep embedded notes short.
If a reusable note gets long, add a short section such as ## Embed or ## Short Version, then embed only that section.
Glossary notes should include a stable ## Definition section. That section is the default embed target for modules and labs.
Broken, ambiguous, or cyclic embeds should fail the intranet build. Obsidian may tolerate fuzzy references, but the shared site should not quietly publish missing or incorrect reference material.
Source: docs/embed-policy.md