Support transclusion of files within Markdown Preview
Visual Studio Code Extension for the built-in Markdown Preview to support transculsion of further files.
The following 2 syntaxes are supported and can be used at anytime
:(file.md)
!!!include(file.md)!!!
- Output when referenced file is not found:
File 'pathToFile/file.md' not found
- Output for circular reference:
Circular reference between 'pathToFile/file.md' and 'pathToParentFile/partent.md'
Content
Examples
Example for syntax based on proposal for CommonMark.org
Example for syntax from Markdown-It-Include plugin
Options
Provide alternative text when file cannot be found
:[Alternative Text](https://github.com/SIPS1980/vscode-markdown-preview-include/blob/master/file.md)
- To include file name in output use:
{{FILE}}
E.g. :[Alternative Text for {{FILE}}](https://github.com/SIPS1980/vscode-markdown-preview-include/blob/master/file.md)
Provide alternative text for circular reference
:[|Alternative Text](https://github.com/SIPS1980/vscode-markdown-preview-include/blob/master/file.md)
To include file name in parent: {{PARENT}}
E.g. :[|Alternative Circular Text with {{PARENT}}](https://github.com/SIPS1980/vscode-markdown-preview-include/blob/master/file.md)
To include file name in child use: {{FILE}}
E.g. :[|Alternative Circular Text with {{FILE}}](https://github.com/SIPS1980/vscode-markdown-preview-include/blob/master/file.md)
Omit output if file cannot be found or if there is a circular reference
:[](https://github.com/SIPS1980/vscode-markdown-preview-include/blob/master/file.md)
Use Cases
Include copyright on multiple markdown files
Content of file copyright.md with copyright notice in includes folder
Copyright © 2019 Company Name - All rights reserved
Files referencing copyright.md in includes folder
Text with information
:[Copyright Notice][includes/copyright.md]
This will produce the following output
Text with information
Copyright © 2019 Company Name - All rights reserved
Include file containing important links and reference them
Content of file links.md with multiple links defined in includes folder
[GITHUB]: https://github.com
[VSMARKETPLACE]: https://marketplace.visualstudio.com
Include links.md in the top of the file where links shall be referenced and use them in the content
:[includes/links.md]
This is a link to [Github][GITHUB]
This will produce the following output
This is a link to Github
Multiple editors working on a large document
Splitting up the document, for example into chapters, provides the possibility for multiple editors working sections of the document. One master document can then include the individual sections for final render.
Example content of file chapter1.md
## Chapter 1
Text for Chapter 1
Example content of file chapter2.md
## Chapter 2
Text for Chapter 2 including a link to [Github][GITHUB]
Bringing it all together
# Document Title
:[includes/links.md]
:[Chapter 1](https://github.com/SIPS1980/vscode-markdown-preview-include/blob/master/chapter1.md)
:[Chapter 2](https://github.com/SIPS1980/vscode-markdown-preview-include/blob/master/chapter2.md)
---
:[Copyright Notice][includes/copyright.md]
This will produce the following output
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
This Visual Studio Code Extension was inspired by
