Includes

<p:include> is a declarative HTML element that includes a fragment of another document (or of the site as a whole) into the current page, resolved by a CSS selector at request time.

Unlike traditional template partials, included fragments remain addressable, authorisable, and writable through Pagelove’s HTTP and selector‑based model.

Namespace declaration

include lives in the Pagelove server-side-processing namespace https://pagelove.org/1.0. Declare it on an ancestor element (usually <html>); the prefix can be any valid XML prefix, but p is conventional and is used throughout these docs:

<html xmlns:p="https://pagelove.org/1.0">

The element-form snippets below show only the <p:include> element itself; each assumes this declaration is present on an ancestor.

Element form

<p:include
  selector="..."
  resource="..." />

Attributes:

selector (required)
resource (optional constraint)

Attribute semantics

`selector` (required)

A CSS selector identifying the fragment to include.

The selector is evaluated against a set of candidate resources determined by the resource attribute (if present) or the entire site graph (if not).

`resource` (optional)

Constrains the search space for the selector.

When present, only resources whose path matches the value(s) of resource are searched. Glob-style (*, ** & ?)wildcards are supported

When omitted, the selector is evaluated across the entire site graph.

resource does not mean “include the whole resource”. A selector is always required.

This is invalid:

<p:include resource="/partials.html" />

This is valid:

<p:include resource="/partials.html" selector="header#nav" />

Resolution model

Given:

<p:include selector="S" resource="R?" />

The server resolves the include as follows:

Determine the candidate resource set:
- If resource is present: all resources matching resource.
- Otherwise: the entire site graph.
Evaluate selector within each candidate resource.
Collect all matching elements across all candidates.
Apply cardinality rules (below).
If resolution succeeds, materialise the matched element in place of the <p:include> node, retaining a link to the origin resource and element so that mutations write through to the source.

Cardinality rules

<p:include> is defined to resolve to exactly one element.

The following rules are enforced:

0 matches → request fails with:

404 Not Found

>1 matches → request fails with:

500 Internal Server Error

Multiple matches are treated as a site integrity failure, not a client input error. An include is expected to identify a single canonical fragment. Ambiguity indicates incorrect site composition.

Examples

Global selector include

Searches the entire site graph.

<p:include selector="#partials header#nav" />

Constrained include

Searches only within /partials.html.

<p:include
  resource="/partials.html"
  selector="header#nav" />

Basic include resolves a fragment from another document

Store a partial containing a navigation header, then a page that includes it via <p:include>:

<!DOCTYPE html>
<html xmlns:p="https://pagelove.org/1.0">
<body>
  <p:include selector="#nav" resource="/sspi-inc-partials/*" />
  <main><p>Page content here.</p></main>
</body>
</html>

When the page is requested, the include is resolved and the fragment is inlined:

GET /sspi-inc-basic.html

HTTP/1.1 200

<!DOCTYPE html>
<html>
<body>
  <header id="nav">Navigation</header>
  <main><p>Page content here.</p></main>
</body>
</html>

The <p:include> element is gone, replaced by the actual <header> from the partial. xmlns:p — like every xmlns:* declaration in the composed document — has been stripped.

Interaction with HTTP Document Mutation (PUT, POST & DELETE)

Included fragments retain their origin identity.

When a client performs a mutating HTTP request (such as PUT) targeting an element that originated from an included fragment:

The modification is applied to the origin resource, not the including document.
Authorization is evaluated against the composed page the request is addressed to — the document the include appears in — not the origin. The origin resource therefore needs no rule of its own permitting the write (a rule on the composed page is both necessary and sufficient).
Shape constraints are evaluated against the origin resource, where the mutation lands.
Concurrency control (ETags) is performed against the origin resource.

If an include fails to resolve uniquely, no write is attempted.

Summary

<p:include> provides deterministic, selector‑based document composition across the site graph.

It:

Requires a selector
Optionally constrains search using resource
Enforces single‑match resolution
Treats ambiguity as a server integrity failure
Preserves fragment provenance for authorization, validation, and write‑through semantics

This makes fragment inclusion a first‑class, HTTP‑addressable primitive rather than a template‑time convenience.