# 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](https://en.wikipedia.org/wiki/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`:

| Style         | Source        | Result           |
| :------------ | :------------ | :--------------- |
| `plain`       | `[[My Note]]` | `My Note`        |
| `emph`        | `[[My Note]]` | `*My Note*`      |
| `strong`      | `[[My Note]]` | `**My Note**`    |
| `underline`   | `[[My Note]]` | `<u>My Note</u>` |
| `at_file_ref` | `[[My Note]]` | `@"My Note.md"`  |

> #### Configuration {: .info}
> Although the system default is `plain`, the configuration file generated by `magma init` sets the link resolution style to `at_file_ref`. This is the recommended setting for coding agents.


## 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:**
```markdown
Here is the overview:

![[Project#Overview]]
```

**Resolved:**
```markdown
Here is the overview:

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



> #### Critical: Paragraph Requirement ⚠️ {: .warning}
> Inline transclusions are only resolved correctly if they stand in their **own paragraph**. They will fail to resolve if they are part of a list, a quote, or directly attached to other text.
> 
> A common "gotcha" is the spacing after headers or lists. To be recognized as a separate paragraph by the underlying processor (Pandoc), there **must be a blank line** before the transclusion.
> 
> **❌ Incorrect (Will not resolve):**
> 
> ```markdown
> # 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:**
```markdown
### ![[Project#Overview]]
```

**Resolved:**
```markdown
### 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:**
```markdown
### My Custom Title ![[Project#Overview]]
```

**Resolved:**
```markdown
### My Custom Title

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


---

> #### Warning {: .warning}
> **Intra-document transclusions** (referencing a section within the *same* file) are currently not supported.