Using InsertPlugin

The InsertPlugin embeds another page's content — or one section of it — into the current page at render time. The inserted content stays live: edits made to the source page show up next time the host page is rendered. See Plugins for a complete list of available plugins.

Syntax

Three forms are supported:

[{Insert page='Pagename'}]
[{Insert pagesection='Pagename#Heading'}]
[{Insert pagesection='Pagename?section=N'}]
[{Insert pagesection='Pagename?section=N', caption='My Heading'}]
[{Insert pagesection='Pagename?section=N', caption='none'}]

The first form inserts the whole page. The second and third forms insert a single section, identified either by its heading text or by its 0-based section index (the same number the editor uses in the ?section=N URL when editing a single section). The optional caption parameter (last two forms) renames or removes the inserted heading — see #Captions.

The inserted block always reads as it does on the source page: a heading that uses the page's own title shows the source page's title, not the page you embedded it into.

Parameters

At least one of page or pagesection must be provided. An empty target renders nothing.

Examples

Full page

Embed the entire content of a page named Pregnancy:

[{Insert page='Pregnancy'}]

Section by heading

Embed only the Symptoms section of the same page. Heading matching is case-insensitive and whitespace-trimmed; the first matching heading wins. The section runs from that heading to the next heading of the same or higher level.

[{Insert pagesection='Pregnancy#Symptoms'}]

Section by index

Embed the third section (0-based: section index 2). This is the same number that appears in the editor's URL when you choose "edit this section":

[{Insert pagesection='Pregnancy?section=2'}]

How sections are counted

• Section numbers are 0-based and count every heading on the page, at any level (# … ######), in order — the same number the section-edit URL uses.
• The page's frontmatter (the --- … --- block at the top) does not count.
• Headings written inside a fenced code block (between ``` fences) are not counted for ?section=N.
• A section runs from its heading down to the next heading of the same or higher level, so any deeper sub-headings are included with it.
• One subtlety: the #Heading form does not skip headings inside code fences when it counts, while ?section=N does. On a page that puts # lines inside a code block the two forms can pick different sections — prefer ?section=N there.

Captions

By default the inserted heading is:

• Section insert — the section's own heading, exactly as it reads on the source page.
• Whole-page insert — an ## heading with the source page's title is added at the top so the block is identifiably that page.

The caption parameter overrides that default:

[{Insert pagesection='Pregnancy?section=2', caption='Key Symptoms'}]

renames the inserted heading to Key Symptoms (keeping its heading level). To drop the heading entirely and embed only the body, use a removal token — none, off, false, no, or an empty value:

[{Insert pagesection='Pregnancy?section=2', caption='none'}]

Omit caption to keep the default heading described above.

What the Reader Sees

Below every successful insert, a small attribution link is rendered so readers (and editors) know the content is transcluded and where to go to actually edit it. The link target is the source page itself (/view/Pagename):

↪ from Pregnancy

For sectional inserts, the section label is appended — the heading text for the #Heading form, or #N for the ?section=N form:

↪ from Pregnancy (section: Symptoms)
↪ from Pregnancy (section: #2)

Editing Inserted Content

Edits happen on the source page only. The inserted block on the host page is a render-time read of the source — there is no inline editor on it. Click the attribution link to navigate to the source page and edit there. The next time the host page is rendered, the change shows up.

What Happens When Things Go Wrong

The notices keep the insert position visible on the host page so an editor knows something was meant to render there, but they never break the host page itself.

Notes

• Other plugins inside an inserted page ([{Image ...}], [{Counter}], etc.) DO evaluate when the inserted content is rendered. Only [{Insert ...}] is suppressed to prevent recursion.
• Insert reads the target page each time the host is rendered. There is no manual cache to invalidate after an edit — the next render picks up the change.
• Heading matching is case-insensitive but otherwise exact. Pregnancy#symptoms and Pregnancy#Symptoms both match ## Symptoms in the source.