# Transclusion or including sub-documents for reuse

**URL:** <https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270>\
**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:** 1\
**Showing post:** 10

<div class="post-metadata">

**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")

</div>

> [@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

```
<!ENTITY ref SYSTEM "http://example.com/text.xml">

```

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_.)

---

_[View the full topic](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270)._