Markdown Preview Transclusion
Seamlessly include external files in your Markdown Preview
A Visual Studio Code extension that extends the built-in Markdown Preview
with the ability to transclude content from other files —
keeping your documentation modular, maintainable, and DRY.
Get Started · Syntax · Options · Use Cases
⚡ Quick Start
Drop any of these syntaxes into your .md file and open Markdown Preview:
:(chapter.md) ← CommonMark proposal
!!!include(chapter.md)!!! ← Markdown-It-Include style
::include{file=chapter.md} ← Directive-based
The referenced file's content appears inline in the preview. That's it.
🔍 How It Works
| Scenario |
Preview output |
| ✅ File found |
Content rendered inline |
| ❌ File not found |
File 'path/file.md' not found |
| 🔄 Circular reference |
Circular reference between 'child.md' and 'parent.md' |
Both error messages are fully customizable — see Options below.
📸 Syntax in Action
|
CommonMark-style
|
Markdown-It-Include-style
|
🛠 Options
Custom "file not found" message
:[Your custom message](https://github.com/sergeydigl3/vscode-markdown-preview-include-gitlab/blob/HEAD/missing-file.md)
Use {{FILE}} to insert the filename dynamically:
:[⚠ Could not locate {{FILE}}](https://github.com/sergeydigl3/vscode-markdown-preview-include-gitlab/blob/HEAD/missing-file.md)
|
Custom "circular reference" message
:[|Your circular-ref message](https://github.com/sergeydigl3/vscode-markdown-preview-include-gitlab/blob/HEAD/file.md)
Placeholders: {{PARENT}} — parent file · {{FILE}} — child file
:[|🔄 Loop detected: {{FILE}} ↔ {{PARENT}}](https://github.com/sergeydigl3/vscode-markdown-preview-include-gitlab/blob/HEAD/file.md)
|
Suppress all error output
Pass an empty label to silently skip missing or circular files:
:[](https://github.com/sergeydigl3/vscode-markdown-preview-include-gitlab/blob/HEAD/file.md)
|
💡 Use Cases
📄 Reusable copyright footer
Create includes/copyright.md:
Copyright © 2019 Company Name - All rights reserved
Reference it in any document:
Text with information
:[Copyright Notice](https://github.com/sergeydigl3/vscode-markdown-preview-include-gitlab/blob/HEAD/includes/copyright.md)
Result →
Text with information
Copyright © 2019 Company Name — All rights reserved
🔗 Shared link definitions
Create includes/links.md:
[GITHUB]: https://github.com
[VSMARKETPLACE]: https://marketplace.visualstudio.com
Include at the top of your document, then use references anywhere:
:(includes/links.md)
Check out the project on [Github][GITHUB].
Result →
Check out the project on Github
👥 Multi-author large documents
Split a document into chapters so multiple editors can work in parallel, then assemble in one master file:
chapter1.md
## Chapter 1
Text for Chapter 1
chapter2.md
## Chapter 2
Text for Chapter 2 including a link to [Github][GITHUB]
master.md
# Document Title
:(includes/links.md)
:(chapter1.md)
:(chapter2.md)
---
:[Copyright Notice](https://github.com/sergeydigl3/vscode-markdown-preview-include-gitlab/blob/HEAD/includes/copyright.md)
Result →
Document Title
Chapter 1
Text for Chapter 1
Chapter 2
Text for Chapter 2 including a link to Github
Copyright © 2019 Company Name — All rights reserved
🙏 Credits & Inspiration
This extension stands on the shoulders of:
Made with ❤️ for the Markdown community
