Create a Page template

A Page template defines the layout around each Page’s content. For example, write an article once, then let the template supply its title, date, body position and table of contents. Templates work in Cloud and self-hosted Typeroll CMS.

If you want a section copied into a page instead, use a block template.

Recommended: build the template with your AI agent

A connected AI agent can create and refine Page templates, define the Content type’s fields and connect those fields to the layout. This is especially useful when a design needs several blocks, responsive settings or consistent styling across many Pages. Describe the result you want; let the agent handle the block structure and API calls.

For example:

For this Site and Version, inspect our Articles content type and its fields.
Create an Article template using our existing styles, with one H1, a date,
an optional featured image, the Page body and an automatic table of contents.
Make it the default for Articles. Preview two articles with different content
at mobile and desktop widths, including one without an image. Show me the
result and which Pages will be affected. Do not deploy the site.

The agent should inspect existing templates before creating another one and use the same Site and Version throughout. It operates with the permissions you grant; review changes and publication impact before deploying. After setup, editors write each Page’s content normally without rebuilding its layout.

Use the editor to inspect and fine-tune the result, or follow the manual workflow below. MCP and REST examples follow it.

1. Create the layout

Select the Site and intended Version, open Templates → New template, and enter:

• Template ID: article-layout (a stable machine name).
• Label: Article (the name editors see).
• Starting layout: Article.

Open the created template. Starting layouts are editable block trees, not locked themes. Other starters include Blog, Checklist, Team, Events, Products, Profile, Landing and Custom. A starter may reference sample fields: match those to your content type before using it.

2. Keep the content dynamic

In the template editor, use the block library to arrange the layout:

Block	What it reads
Page title	The current Page’s title; normally your single H1
Page date	The selected date field, such as date_published
Page featured image	The field selected in its Image field setting
Page content	The Page’s own body blocks
Table of contents	The headings actually rendered on that Page
Page field list	Public custom fields, with empty rows hidden by default

The Article starter already includes a title, date, breadcrumbs, a content slot and a table of contents. Add a featured image if you need one. If your Content type stores the image in fields.featured_image, set the image block’s Image field to featured_image; its own default is og_image.

Keep a Page content slot wherever the article body should appear. Without it, a template can show metadata but will not show the Page’s body. Set its Content spacing to Article for article rhythm. Choose which heading levels the table of contents includes; do not maintain a separate list of links.

When the template supplies the H1, start body sections at H2. Use visual size controls to adjust appearance without changing the semantic heading level.

Template changes save in the editor. Wait for Saved, then set the template’s status to Published to make it available in Page template choices. This makes the template usable in the CMS; it does not deploy the website.

3. Assign it to a Content type

Open Content types, select your Articles type, and find Page templates. Choose Article as its Default template. If you enable Limit the templates editors can choose, include the default and any alternatives in that selection.

A type defines fields, routes and listing defaults. It can allow several Page templates. A template can be shared across compatible types; its applies_to restriction controls compatibility.

4. Write and preview two Pages

Create two Pages with the Articles content type and different titles and bodies. Open Meta → Template on each and choose Use content type’s default template. Save, then preview both Pages at a narrow and wide viewport.

Check that each has its own title, body and contents links. Try an empty optional image or field to see how the layout behaves. A core/field_list hides its heading too when no rows are visible.

To give one Page a different layout, select an allowed alternative under Template and save. That Page keeps its explicit choice if the type’s default changes later. Choose the inherited option again to follow the default.

5. Publish when ready

Save Page working copies, review the selected Version and deploy through the normal publication flow. Template edits can affect many Pages; inspect the publication impact before deploying. A template cannot be deleted while Pages or Content types still reference it.

The same workflow through MCP or REST

Call create_page_template with:

{
  "name": "article-layout",
  "label": "Article",
  "starter": "article",
  "status": "published",
  "version": "main"
}

For REST, send the same definition without version to POST /api/v1/sites/{siteId}/page-templates?version=main. You may supply blocks instead of starter, but not both. Retain the returned template ID.

Set an existing Content type’s default with update_content_type:

{
  "name": "articles",
  "patch": { "template": "article-layout" },
  "version": "main"
}

If the type has an explicit allowed_templates list, include the template there too. Use a Page’s template for an override; set it to null to restore inheritance. Those Page changes follow Save/Discard.

Use read_page_template before editing, and address its blocks with target: { kind: "template", id: "article-layout" }. For isolated work, replace main with the same site version on every supported operation. Definition writes save immediately; inspect tool results for any working-copy changes.

Troubleshooting

Symptom	Check
Template is absent from the Page picker	Its Published status, selected Version, compatibility and the type’s allowed list
Title appears twice	Keep H1 in the template; remove the duplicate body heading or make it H2
Body is missing	Add template_content_slot to the template
Image is missing or the wrong image appears	Match the template image block’s field to the Page field holding the image
A Page ignores the new default	Clear its explicit template override
Preview changed but the live site did not	Save the intended content and complete a successful deployment

See the Content type and template reference for sorting, field permissions and template restrictions, and the block catalog for all dynamic blocks.

Check it

Preview a Page of the Content type with get_page_preview or the editor’s preview: the template’s title, image and body slot show that Page’s own content. After the next publication, the launch readiness report confirms that each Page renders exactly one H1, counting the template.