What is Transclusion in Markdown Notes?

Transclusion is the inclusion of a section, paragraph, or entire document from one source file directly inside another document by reference, rather than copying and pasting static text.

Coined in 1980 by Ted Nelson in his vision of Project Xanadu, transclusion represents one of the most powerful concepts in hypertext theory. When you transclude content, the host document displays the target content live. If you edit the original source note, every document that transcludes it updates automatically, preserving a single source of truth.

Transclusion syntax in modern Markdown

Extended note-taking systems like Obsidian and Oyma use an exclamation mark prefix before double square brackets to denote transclusion:

1. Entire document transclusion

# Comprehensive System Architecture

Below is our live threat model analysis:
![[Threat Model 2026]]

2. Heading-level section transclusion

You can embed a specific subsection of a large document using a hash symbol (#):

### Key Decisions from Yesterday
![[2026-10-09 Architecture Alignment#Decisions & Next Steps]]

Only the designated heading and the content beneath it (up to the next heading of equal or higher rank) will render inside the host note.

3. Atomic block transclusion

You can embed an individual bullet point or paragraph by attaching a block identifier (^block-id):

![[Security Standards#^zero-telemetry-invariant]]

Why transclusion eliminates copy-paste drift

In traditional word processing, teams copy and paste standard boilerplate—such as pricing tables, company biographies, or terms of service—across dozens of files. Inevitably, the pricing changes, leaving outdated information scattered across forgotten documents.

Transclusion enforces modular architectural hygiene:

• Define your security invariants once in Security Policy.md.
• Transclude that section across ten client project proposals.
• When the policy updates, all ten proposals reflect the change instantly.

Transclusion in Oyma on macOS

In Oyma:

• Transcluded notes and sections render as elegant, bordered preview cards within the live-preview editor.
• Clicking the embed card jumps directly to the source document for editing.
• Local SQLite caching ensures that transcluded blocks render instantaneously without lag, providing true single-source-of-truth document composition on your Mac.