# Transclusion or including sub-documents for reuse **URL:** \ **Category:** Extensions\ **Created:** [September 4, 2014, 10:18am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270 "2014-09-04T10:18:45Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![SvenDowideit](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/svendowideit/32/165_2.png) [@SvenDowideit](https://talk.commonmark.org/u/SvenDowideit)\ **Post date:** [September 4, 2014, 10:18am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/1 "2014-09-04T10:18:45Z")
Coming from Foswiki, and now working on Docker documentation in markdown, I stongly miss having built in transclusion. If there’s any chance something basic can be included in Standrd Markdown - ala [http://fletcher.github.io/MultiMarkdown-4/transclusion](http://fletcher.github.io/MultiMarkdown-4/transclusion) that would be awesome - copy and paste is such a painfully pointless excercise… ---
**Author:** ![riking](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/riking/32/23_2.png) [@riking](https://talk.commonmark.org/u/riking)\ **Post date:** [September 4, 2014, 6:29pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/2 "2014-09-04T18:29:08Z")
I think it should be an extension - transclusion is not useful for all cases, and the resolution of the transcluded document name is inherently domain-specific. ---
**Author:** ![MathieuDuponchelle](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mathieuduponchelle/32/2113_2.png) [@MathieuDuponchelle](https://talk.commonmark.org/u/MathieuDuponchelle)\ **Post date:** [February 7, 2016, 10:10pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/3 "2016-02-07T22:10:44Z")
+1 , this is a very nice feature. I don’t agree that “the resolution of the transcluded document name [should be] inherently domain-specific.” , if the “inclusion target” is specified to be a file name. I have implemented this in a code documentation tool I’m writing, with the following syntax: - {{ my\_file }} -\> include the file and parse it as markdown - {{ my\_file[start:end] }} -\> include the lines comprised between start and end and parse them as markdown. - {{ my\_file.recognized\_language\_extension#symbol\_name } -\> for example { my\_file.c#foo\_bar } , retrieve the symbol named `foo_bar` in `my_file.c` , and include its content as a markdown code block . the range syntax can also be used in combination with this, for example { my\_file.c#foo\_bar[2:4] } will only include the lines 2 to 4 in the local scope of the given symbol. I think the first form is quite true to the spirit of the markdown, I’m a little biased about the second form because I’ve written too much python, and the third form could make sense if CommonMark supports anchors (not sure if it does). As for it being an extension, I do think this feature can be generically useful. ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [February 8, 2016, 8:26am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/4 "2016-02-08T08:26:37Z")
I’ve added this topic to the [list of proposed extensions](https://github.com/jgm/CommonMark/wiki/Proposed-Extensions) and requested that the topic is moved to the “Extensions” category. ---
**Author:** ![vdb](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/v/c77e96/32.png) [@vdb](https://talk.commonmark.org/u/vdb)\ **Post date:** [February 13, 2016, 5:52pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/5 "2016-02-13T17:52:51Z")
-1 Nice feature, but… > if the “inclusion target” is specified to be a file name. In case of files there is no need in special support from CommonMark processor, because transclusion can be easily done by any external preprocessor, like cpp or m4. Transclusion _can be_ helpful in other cases, though. For example, transclusion of wiki pages. But in this case it is quite domain-specific. ---
**Author:** ![MathieuDuponchelle](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mathieuduponchelle/32/2113_2.png) [@MathieuDuponchelle](https://talk.commonmark.org/u/MathieuDuponchelle)\ **Post date:** [February 24, 2016, 4:19pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/6 "2016-02-24T16:19:02Z")
> case of files there is no need in special support from CommonMark processor, because transclusion can be easily done by any external preprocessor Not true, transclusion should not happen in code blocks for example ---
**Author:** ![theGiallo](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/thegiallo/32/924_2.png) [@theGiallo](https://talk.commonmark.org/u/theGiallo)\ **Post date:** [March 5, 2016, 4:10pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/7 "2016-03-05T16:10:47Z")
Yeah, it could be done by another tool, like any other feature of MD. I think the ability to include other files could give a lot more power to MD. My main use is repository readmes, and I would really like to be able to include files in the main readme. Having to use an external tool would vanish the benefit. ---
**Author:** ![jmatsushita](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jmatsushita/32/957_2.png) [@jmatsushita](https://talk.commonmark.org/u/jmatsushita)\ **Post date:** [April 8, 2016, 7:07am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/8 "2016-04-08T07:07:53Z")
Hi there, I wanted to point out another transclusion syntax that I’ve grown quite fond of which is proposed in the [hercule](https://github.com/jamesramsay/hercule) library and used to compose API Blueprints. ```auto Simple extension of markdown link syntax :[Title](link.md) (preceding colon :) ``` The big plus is graceful degradation into links, and possible context passing. ---
**Author:** ![james](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/j/bc8723/32.png) [@james](https://talk.commonmark.org/u/james)\ **Post date:** [November 23, 2016, 5:19pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/9 "2016-11-23T17:19:35Z")
The great text editor iA Writer has introduced content blocks with a new syntax ([https://ia.net/writer/support/general/content-blocks#toc](https://ia.net/writer/support/general/content-blocks#toc)): ```auto Simple example /transclude.md 'Example link (title/caption is ignored for text file types)' ``` It would be nice to see a standard syntax emerge for transclusion. Such variation in syntax is frustrating and creates lock-in to specific tooling. As pointed out by @jmatsushita, one of the reasons hercule uses a precedinge colon is that it degrades to standard link in environments that don’t support transclusion, reducing the lock-in. ---
**Author:** ![tin-pot](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/tin-pot/32/810_2.png) [@tin-pot](https://talk.commonmark.org/u/tin-pot)\ **Post date:** [November 29, 2016, 2:44pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/10 "2016-11-29T14:44:44Z")
> [@jmatsushita](#): > > `Simple extension of markdown link syntax :[Title](link.md) (preceding colon :)` > > The big plus is graceful degradation into links, and possible context passing. Looks reasonable to me, as long as the analogy to _CommonMark_’s “indirect” link syntax is also taken into account: ``` Simple extension of indirect link syntax :[here][ref] in _CommonMark_ text [ref]: http://example.com/text.md "Example text to include" ``` But where does the `here` and `Example text to include` text strings go, when after all the string `:[here][ref]` is supposed to be _replaced_ with the “transcluded” text? They would just be discarded and have no purpose, right? So a symbolic reference or an in-line URL would be enough, either written as `:[ref][]` (with the same “fall-back” property), or as: ``` Simple analogy to indirect link syntax :[ref] in _CommonMark_ text. Analogy to direct link syntax :(http://example.com/text.md) in _CommonMark_ text. [ref]: http://example.com/text.md ``` Now the first case looks suspiciously close in intent, syntax, and behaviour to ``` Existing syntax: &ref; in _CommonMark_ text (via *entity reference*). ``` while the second case (the inline URL) looks pretty ugly and error-prone to me. And why shouldn’t we be honest and admit at this point that we re-invent _external entities_ in _CommonMark_— the exact same thing that in XML would be done by placing ``` ``` in the _internal subset_ and then referencing (“transcluding”) this text with literally the same syntax `&ref;` as given in the example above? And since we have re-invented _external entities_ already, why not re-invent _internal entities_, too? Which could look in _CommonMark_ like this: ``` Simple extension: insert &here; some internal entity. [here]: "at this point" ``` Maybe it seems too far a step to use `&ref;` for these tricks too, and it may seem that `:[ref]` would indicate clearer that “something special” is going on here. But the flexibility and consistency that using `&ref;` in these cases too would entail—adopted directly from XML—is worth considering, I would think. (And note that this does in fact nothing else but replicate the purpose and use of _external_ and _internal_ XML _entities_ in _CommonMark_.) ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [August 12, 2017, 9:51am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/11 "2017-08-12T09:51:47Z")
I like the iA Writer syntax. In the link @james posted, there’s some further examples for transcluding text, tables, and images: ```markdown /Section.txt "Section" /Balance Sheet.csv 'Finances' /images/Structure.jpg (Data Flow) ``` The use of a forward slash for all transcluded file types is easy to remember. I think the iA Writer syntax is even more intuitive for causal writers than Markdown’s regular image syntax. In some ways this syntax is reinventing the wheel. In Markdown we already have a syntax for including images, which could be [extended for other embedded files](https://talk.commonmark.org/t/embedded-audio-and-video/441). For the iA Writer examples, we could use this syntax: ```markdown ![Section](section.txt) ![Finances](Balance Sheet.csv) ![Data Flow](images/Structure.jpg) ``` However, the text in brackets or quotes in the iA Writer syntax is displayed as a caption - whereas in Markdown, alternative text is not displayed as a caption without some non-standard post-processing. So there might be a case for using the iA Writer syntax for _embedded content with optional captions_, rather than [hijacking the Markdown image syntax reserved for alt or title](https://talk.commonmark.org/t/image-tag-should-expand-to-figure-when-used-with-title/265) to display figures. There’s also the question of how this information should be transcluded. For example, iA Writer presents the CSV file as a table. So there would need to be file type specific rules regarding transclusion. This follows on from the embedded audio/video discussion. As CommonMark extensions, would there be harm in supporting both? Markdown has always followed [TMTOWTDI](https://en.wikipedia.org/wiki/There's_more_than_one_way_to_do_it). ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [August 23, 2017, 11:28am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/12 "2017-08-23T11:28:28Z")
The generated HTML from `/images/Structure.jpg (Data Flow)` is: ```auto
Data Flow
Data Flow
``` So, the figure caption doubles as the image’s alternative text, making it easier (and less repetitive) to add captioned images to a document quickly. There was also some [discussion earlier](https://talk.commonmark.org/t/why-not-allow-images-without-alt/617) about making alt text optional in some scenarios (e.g. quickly adding a set of images to a forum post), so this might be a nicer solution for those cases (no empty square brackets). `/images/Structure.jpg` produces: ```auto
``` ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [August 24, 2017, 1:01pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/13 "2017-08-24T13:01:24Z")
iA Inc have published a spec for Markdown Content Blocks (transclusion) over on GitHub: > **[GitHub - iainc/Markdown-Content-Blocks: File transclusion syntax for Markdown.](https://github.com/iainc/Markdown-Content-Blocks)** > > File transclusion syntax for Markdown. > We think that content blocks are a natural extension of Markdown. We’d be happy if more apps supported them. We’re publishing this spec to aid the process, and to start the conversation around it. We’re just getting started. Your suggestions are welcome. ---
**Author:** ![anon20778841](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/a/8e7dd6/32.png) [@anon20778841](https://talk.commonmark.org/u/anon20778841)\ **Post date:** [August 1, 2022, 5:15am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/14 "2022-08-01T05:15:30Z")
Transclusion is something that Ted Nelson talked about from the beginning and is important in text markup whether for xanadu, html, markdown or xml etc. There are several implementations in markdown that do transclusion, it would be interesting in this sense to have a common and unique markup for this. In such a connected, dynamic and unique world I believe this: _ **transclusion in commonmark** _. In my opinion this feature would make my life easier - it would be something I could use more often, it would be a replacement for Obsidian, Notion, org-mode. ---
**Author:** ![anon20778841](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/a/8e7dd6/32.png) [@anon20778841](https://talk.commonmark.org/u/anon20778841)\ **Post date:** [August 2, 2022, 11:35pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/16 "2022-08-02T23:35:50Z")
> [@anon20778841](#): > > . transclusion or including subdocuments for reuse with tables or inline/embedded table #### How to have transclusion or including subdocuments for reuse with tables or inline/embedded table? 1. `[Filename](filename.md)` - @jmatsushita as a proposal 2. `#include "filename.md"` - @anon20778841 as a proposal 3. `[cite](https://oleb.net/2020/swift-docker-linux/#:~:text=running,container)` - @anon20778841 as a proposal: _“Proposal to allow specifying a text snippet in a URL fragment inside blockquotes in CommonMarkdown”_ ---
**Author:** ![SRNissen](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/srnissen/32/2816_2.png) [@SRNissen](https://talk.commonmark.org/u/SRNissen)\ **Post date:** [November 6, 2023, 8:47am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/17 "2023-11-06T08:47:52Z")
I notice a banner up top: > Please note the CommonMark spec is currently **frozen with respect to features** , but there are supersets of or extensible implementations of CommonMark that may support what you need. Does that include features like this that are already on the proposed list, or is it exclusive to fully novel features? (My apologies if I missed something obvious - a read of [commonmark.org](http://commonmark.org) and a quick google has failed to answer this question) ---
**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\ **Post date:** [November 12, 2023, 12:26am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/18 "2023-11-12T00:26:30Z")
> [@SRNissen](#): > > Does that include features like this that are already on the proposed list, or is it exclusive to fully novel features? Since transclusion wasn’t a feature included in the original Markdown featureset, it would be outside the scope of the featureset specified in the core CommonMark spec. There was some talk of creating specs for CommonMark extensions, but I imagine that would be left to third parties at this point. ---
**Author:** ![kangtian\_pan](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/kangtian_pan/32/2899_2.png) [@kangtian\_pan](https://talk.commonmark.org/u/kangtian_pan)\ **Post date:** [January 31, 2024, 1:46am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/19 "2024-01-31T01:46:58Z")
It’s been challenging to push forward with this feature. Any new developments? ---
**Author:** ![Sim\_Tov](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/sim_tov/32/2901_2.png) [@Sim\_Tov](https://talk.commonmark.org/u/Sim_Tov)\ **Post date:** [February 14, 2024, 11:49am UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/20 "2024-02-14T11:49:25Z")
I would suggest this syntax for file inclusion: ```auto +[Title](link.md) ``` I find `+` sign to be intuitive for adding/including something… Is there anything new on inclusion of this extension into cmark? ---
**Author:** ![taufik-nurrohman](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/taufik-nurrohman/32/3478_2.png) [@taufik-nurrohman](https://talk.commonmark.org/u/taufik-nurrohman)\ **Post date:** [September 23, 2026, 1:33pm UTC](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/21 "2026-09-23T13:33:57Z")
I still feel that the [auto-link syntax](https://spec.commonmark.org/0.31.2#autolink) has so much potential. Since it doesn’t rely on a set of standard URL schemes, you could create a “transclusion” syntax [as follows](https://github.com/taufik-nurrohman/markdown#idea-embed-syntax): ```md ``` Then, you pre-process it. Use the URL parameter to replace placeholders in the snippet file with its value. Example: ```md ``` Then, in the snippet file: ```md Hello, &name;! ``` Markdown parsers that do not support this syntax will simply treat it as a standard clickable link and treat the variables as invalid HTML entities. This makes it backward compatible: ```html

embed:path/to/file.md?name=Taufik

``` ```html

Hello, &name;!

``` [Next page](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270.md?page=2)