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
  • Provide alternative text for circular reference
  • Omit output if file cannot be found or if there is a circular reference
• Use Cases
  • Include copyright on multiple markdown files
  • Include file containing important links and reference them
  • Multiple editors working on a large document
• Credits

---

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](file.md)

• To include file name in output use: {{FILE}}
  E.g. :[Alternative Text for {{FILE}}](file.md)

Provide alternative text for circular reference

:[|Alternative Text](file.md)

• To include file name in parent: {{PARENT}}
  E.g. :[|Alternative Circular Text with {{PARENT}}](file.md)

• To include file name in child use: {{FILE}}
  E.g. :[|Alternative Circular Text with {{FILE}}](file.md)

Omit output if file cannot be found or if there is a circular reference

:[](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](chapter1.md)

:[Chapter 2](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

• Markdown-It-Include plugin for Markdown-It
• Transclusion conversation in CommonMark.org forum