Help:Labeled section transclusion
 | This help page is a how-to guide. It explains concepts or processes used by the Wikipedia community. It is not one of Wikipedia's policies or guidelines, and may reflect varying levels of consensus. |
Labeled Section Transclusion (LST) offers two basic ways to specify a "section" of a page for transclusion. One way uses the page name and a heading (section title, as seen on the rendered page). The other way enables an arbitrary "section" for transclusion, but it requires markup first in order to add the label.
Three functions can transclude a section from a given page name.
- {{#section:page name|label}} (a labeled section)
- {{#section-x:page name|label}} (all except that labeled section)
- {{#section-h:page name|heading}} (a normal section)
To prepare an arbitrary "section" for a labeled section transclusion, mark it with begin and end attributes inside <section /> tags that contain your label:
Compared to LST transclusion, partial transclusion markup cannot be labeled, and thus the source page cannot have one set of its sections transcluded to one page while having also a different set for another page. A page marked up with partial transclusion tags only, will always transclude the same. But LST and partial transclusion both, can work together on the same page.
These LST functions take additional parameters as explained below. § Example pages provides search links for the articles that currently employ LST so you can see how they are using it.
Common usage.
- Template:Fone preview transcluding a transclusion in the version
- Cite You must have the full definition of a WP:REFNAME on any page that this mult-cited-reference shortcut is neede.
- To render transcluding footnotes.you must tag.
Markup
No markup of the source page is needed if only section titles are used to specify the transclusion. This is the case with #section-h.
For labeling a section for LST transclusion use the following markup.
Section marking
Markup your section boundaries in the source page using two, singular, <section /> tags; for example, to label a section "chapter1":
<section begin=chapter1 />this is a chapter<section end=chapter1 />
Note this is not normal opening-tag, closing-tag HTML. In HTML <section>...</section> is invalid. This parser tag, <section />, is incompatible with an HTML element because MediaWiki markup employs a unique parser tag, added just for the Labeled Section Transclusion extension.
Section transclusion
Use the parser function #section to transclude the section. For example, to transclude section labeled chapter1 from a page called articleX:
{{#section:ArticleX|chapter1}}
Transclude the page but exclude the section
To transclude a page, but exclude a specified section, use the #section-x parser function:
{{#section-x:fullpagename|label}}
or
{{#section-x:fullpagename|heading}}
Optionally, you may add replacement text to the excluded section.
{{#section-x:fullpagename|label|replacement text}}
Example:
{{#section-x:articleX|chapter1|See chapter 1 in [[articleX]].}}
The replacement text will appear in the area where the section is skipped (excluded).
Dealing with stray whitespace
By default, #section will include all the whitespace in the section, which can lead to issues if you're trying to transclude the section into a different article. To solve this, make use of the {{trim}} template, e.g.
{{trim|{{#section:ArticleX|chapter1}}}}
This will get rid of both leading and trailing whitespace, and the article will render as intended.
Other functions
Discontiguous sections
It is possible to have multiple sections with the same name; in this case, every section with that name will be included/excluded. This is especially useful to mark various discussions.
Section ranges
These functions can transclude the whole page, so they have the two, optional argument to specify behaviours: 1) a name-tagged section or heading-title, 2) a range of such named section-tags or section titles, and 3) replacement content for a named section.
{{#section:articleX|chapter1|chapter3}}includes everything from the beginning of chapter 1 to the end of chapter 3. This allows using empty marker pairs to mark one end of the section, possibly in a template.{{#section-h:articleX|chapter1|chapter3}}includes content of chapter1, heading and content of chapter 2.{{#section-x:articleX|chapter1|chapter3}}replaces chapter1 heading and content with the word "chapter3".
Substitution
Instead of transcluding every time, to "transclude" once (to copy), use substitution:
- {{subst:{{#section...}}}}
For example to archive old talk on your talk page, you can copy it to an archive page, then delete it, all using LST:
- Put
<section begin=archive />at the beginning of the section you want to archive and<section end=archive />at the end. (We use "archive" for the label, but any label will do.). This section can be anywhere, and it can be multiple sections. - Save those change to your talk page.
- Create a new archive page. Put {{subst:#section:User talk:pagename|archive}}.
- Save that archive page. The old talk is copied over to it. The transclusion disappears because it was substituted.
- Edit your talk page again. Replace all the wikitext on the entire page with {{subst:#section-x:User talk:username|archive}}. The database page will be transcluded, minus the exact same wikitext in the saved archive, and minus the section tags (which we had labeled "archive").
When using substitution to transclude content on Wikipedia, please use the edit summary to apply reusers' rights and obligations. This applies to any substantial content, and not just article contents.
No template
Currently, no template can facilitate this LST markup because it is necessary to use #tag in order to "preSaveTransform" magic words inside a tag of any kind. For the proper attempt see (the non-functioning) {{section}}.
The only way to evaluate template arguments inside a tag (because of the parsing order) is #tag. LST would need (template) evaluation of the label as the section tag is generated: {{ #tag: section | {{{1}}} }}.
But #tag only produces XML-like (balanced, open-closed, start-end, pairs of) tags, while LST will use a singular, explicitly self closing, tag. So LST tags cannot be generated by any template. Compare actual (only in effect) output:
{{#tag:section|content|begin=label}} →
<section begin=label> content </section> 
with the requested output:
<section begin=label /> content <section end=label />
Example pages
These are searches stored in a link:
- insource:"section h" insource:/\#"section-h"/ (Articles)
- insource:section insource:/\{\{\#section/ (Articles)
- all: insource:"section x" insource:/\#"section-x"/ (entire wiki)
- insource:lst insource:/\#lst/ (Articles)
- insource:lsth insource:/\{\{\#lsth/ (Articles)
- all: insource:lstx insource:/\#lstx/ (entire wiki)