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

Parameter	Type	Default	Description
`page`	string	(none)	Page name for a full-page insert
`pagesection`	string	(none)	`Pagename#Heading` or `Pagename?section=N` for inserting one section; takes precedence over `page` when both are given
`caption`	string	(none)	Rename the inserted heading (keeps its level), or remove it with `none`, `off`, `false`, `no`, or empty. Omit it to keep the default heading (see #Captions)

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

Situation	What is rendered
Target page not found	`Insert: page not found` notice with the page name
Target page is private and the viewer is not its author or an admin	`Insert: page not visible` notice
Requested section index is out of range	`Insert: section N not found in <Pagename>` notice
Heading text does not match any heading in the page	`Insert: section "Heading" not found in <Pagename>` notice
`[{Insert ...}]` appears inside an already-inserted page	Stripped before render — no recursion. Only the outer Insert evaluates.
The page service is temporarily unavailable	`Insert: PageManager unavailable` notice
Looking up the source page failed (transient error)	`Insert: page lookup failed` notice
The source content could not be rendered	`Insert: render failed` notice

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.