Markdown Embeds: Media & Transclusion Guide

![[Target Note]]
![[document.pdf]]
![[meeting-audio.m4a]]
![[Target Note#Specific Section]]

In modern knowledge management, ideas rarely exist in isolation. You often need to quote an entire policy section from an engineering handbook, embed an interactive PDF research paper, include an audio recording from a client call, or composite modular notes into a master document.

Standard Markdown only supports embedding images (![alt](url)). However, Obsidian Flavored Markdown and Oyma introduce powerful transclusion and media embed syntax by prepending an exclamation mark to double-bracket WikiLinks: ![[Target]].

This capability allows you to reuse and recombine knowledge across your vault without duplicating text.

Note transclusion: ![[Note Title]]

To embed the entire contents of another note inline, prefix the WikiLink with an exclamation mark (!):

# Q4 Operational Review

The following section reflects our core privacy invariants:

![[Privacy Architecture]]

Proceeding with the implementation roadmap...

In the rendered view:

• The content of Privacy Architecture displays seamlessly inside a framed card.
• If you edit the original Privacy Architecture note, the transcluded view updates automatically everywhere it is referenced.
• You avoid copy-pasting text across multiple documents.

Section transclusion: ![[Note#Heading]]

When you only need a specific portion of a large reference document—such as an Executive Summary, a Pricing Table, or an Action Checklist—you can transclude just that section:

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

Only the designated heading and the text beneath it (up to the next heading of equal or higher rank) will be rendered.

Block transclusion: ![[Note#^block-id]]

You can transclude a single atomic paragraph or list item using its block identifier:

![[Security Policy#^data-retention-rule]]

The targeted sentence or bullet item renders directly in place, ensuring singular source-of-truth accuracy across your entire knowledge base.

Embedding PDF documents: ![[document.pdf]]

Technical research, whitepapers, contracts, and academic citations frequently arrive as PDF files.

In Oyma and Obsidian, embedding a PDF is as simple as:

![[attachments/ScreenCaptureKit-Whitepaper.pdf]]

In Oyma‘s live-preview editor:

• The PDF renders with a native macOS PDF viewer.
• Readers can scroll pages, zoom in and out, copy text, and search within the document.
• You can even target specific pages: ![[whitepaper.pdf#page=5]].

Embedding audio recordings: ![[recording.m4a]]

For meeting notes, interview debriefs, and voice memos:

![[attachments/2026-10-09-Client-Intake.m4a]]

Oyma renders a native macOS audio player complete with play/pause controls, a scrubbable waveform, and playback speed adjustment. Because audio is stored locally, playback is instantaneous and 100% offline.

Standard Markdown image embeds vs Wikilink embeds

Transclusion in Oyma on macOS

In Oyma:

• Note embeds and media files render with hardware-accelerated Retina clarity.
• Click the corner link on any transcluded card to open the source note immediately.
• All attachments remain organized in your local vault’s attachments/ folder on disk.
• Zero network dependencies, zero cloud hosting, and 100% data sovereignty.

Frequently asked questions

What is transclusion in Markdown?

Transclusion is the inclusion of the contents of one document within another by reference. In Obsidian and Oyma, prepending an exclamation mark to a WikiLink (`![[Target Note]]`) embeds the live, rendered content of the referenced note directly into the current page.

Can I embed a specific heading or section from another note?

Yes. You can transclude a single section by referencing its heading: `![[Target Note#Executive Summary]]`. Only that specific heading and its body text will render within your current note.

How do I embed PDFs and audio files in Markdown?

Use the embed syntax with the file name: `![[whitepaper.pdf]]` or `![[interview.m4a]]`. Oyma renders interactive PDF viewers and playable audio widgets directly inline.

How are embedded media files stored in Oyma?

Oyma stores all attachments (images, PDFs, audio recordings) inside your local vault's `attachments/` folder. Everything lives on your local Mac disk with zero third-party cloud hosting.