The Transclude macro is a tool to include other pages within the current page. This could be a useful tool when building web-pages/sites, but could also be misused. So take care when using it, and try not to break XHTML-conformity. The term transclusion is defined in MeatBall:TransClusion?, and is not a correct English word, but it works.

First a basic example of transclusion:

[[Transclude SomePage]]

Which would transclude/include everything from the page SomePage into the current document. Note that although it's possible to do ''[[Transclude SomePage]]'' this is deprecated due to its non-conforming results. It kind of works, but it breaks Xhtml.

An example of shifting header levels:

[[Transclude {offset=2} SomePage]]

This would lead to the result of all headings within SomePage are shifted by 2. That is a heading on the first level, would now be on the third level. This is useful since it allows the different pages to be conformant within themselvs regarding to header levels, and then when transcluded they are shifted to the correct level within the transcluded document. This will also be propagated downwards into other transcluded documents. Albeit it will stop at the settings of the maximum header level.

Practical transclusions

To illustrate the use of transclusion we'll present some different case studies. No total documents are shown, only the markup needed to produce those documents.

Preparing a book

Through the proper use of transclusion one could rather easily build a book. Firstly build the web site containing all chapters and subchapters as wanted, and letting each and every page start using proper heading levels, that is usually to start at the second level within the page, since the page header is at the first level. Then after writing some chapters make a page building the book like:

== Introduction ==
This book is a collection of web pages from http://www.com.
== Theory ==
[[Transclude {offset=2} Theory]]
=== First Sub Theory===
[[Transclude {offset=3] FirstSubTheory]]
=== Second Sub Theory ===
[[Transclude {offset=3] FirstSubTheory]]
== Experiments ==
We made a lot of experiments, and they all went kaboom!
=== Experiment 1: Something ===
[[Transclude {offset=3} Experiment/Something]]
=== Experiment 2: Nothing ===
[[Transclude {offset=3} Experiment/Nothing]]

When building TaviSubPages

A neat solution on how to build TaviSubPages is to use transclusions. In fact this is already done on some of the subpages of this site. If you look at the source of TaviMacros, it's a transclusion of TaviMacros/Intro. This allows for the use of /Transclude to refer to sibling TaviMacros/Transclude from within the /Intro-page. This produces, in my opinion, much neater intro pages to the different sub pages levels. (I.e. One doesn't have to write TaviMacros/Transclude on the (/TaviMacros)?-page)

This also allows for building nice overviews if one chooses a given name of all the intro pages. From version 0.26 it's possible to do:

[[TitleSearch {list} (*)/Intro$]]

which would result in the list of all intro pages to any subpages in the current tree. In version 0.26, the example will be provided.

In a soon upcoming release, it will also be possible to go directly to the editing of a transcluded page, from the page where the transclusion occurs. This will then be added as a second edit link on the bottom of the page.