Transclusion Resolution

Transclusion is the "superpower" of Magma. It allows you to build complex prompts by referencing existing knowledge instead of copying and pasting it.

What are Transclusions?

A transclusion is a reference to another document (or a section of a document) that is automatically expanded when you "compile" your prompt.

In Obsidian/Magma, a transclusion looks like this:

• ![[Project Overview]] (Include an entire document)
• ![[API Reference#Authentication]] (Include only a specific section)

Why Use Transclusions?

1. Single Source of Truth: Update a piece of documentation once, and every prompt that references it is instantly updated.
2. Modular Prompts: Build a library of "knowledge fragments" (Atomic Notes) and mix-and-match them to create custom context for different tasks.
3. Clean Source Files: Your prompt documents stay short and readable because the "heavy lifting" is done by references.

The Resolution Process

When you copy or execute a prompt, Magma resolves these references. This is not just a simple "search and replace." Magma performs several steps:

• Recursive Expansion: If Note A transcludes Note B, and Note B transcludes Note C, Magma will resolve all of them. It includes protection against infinite recursion.
• Header Level Adjustment: Magma automatically adjusts the # levels of transcluded content so they fit perfectly into the hierarchy of your prompt.
• Comment Stripping: Any <!-- markdown comments --> in your source notes are removed, keeping your prompt clean for the LLM.
• Link Resolution: Internal [[links]] are converted to plain text (or other styles, see below).
• Empty Header Handling: If the transcluded content (after stripping comments) consists only of a header with no content below it, the transclusion is resolved with an empty string.

Link Resolution Styles

Since LLMs don't know how to "click" an Obsidian link, Magma converts [[links]] to plain text during resolution. You can configure this in magma.config/Magma.system.config.md:

The Three Types of Transclusions

Magma supports three ways to transclude content, depending on how you want headers and the prologue (text before the document title) to be handled.

1. Inline Transclusions (Headerless)

Place the transclusion on its own line in their own paragraph. Magma will include the content but strip the source header.

• Prolog Handling: Inline transclusions keep the prologue of the source document.

Source:

Here is the overview:

![[Project#Overview]]

Resolved:

Here is the overview:

[Content of the Overview section goes here...]

# Header
![[Project#Overview]]

2. Empty Header Transclusions (Keep Original)

Put the transclusion in a header line with no title. Magma will keep the original source header and adjust its level.

• Prolog Handling: Empty header transclusions omit the prologue.

Source:

### ![[Project#Overview]]

Resolved:

### Overview

[Content of the Overview section goes here...]

3. Custom Header Transclusions

Put the transclusion at the end of a header line. Magma will replace the source header with your custom one.

• Prolog Handling: Custom header transclusions omit the prologue.

Source:

### My Custom Title ![[Project#Overview]]

Resolved:

### My Custom Title

[Content of the Overview section goes here...]