DocumentationExperience League Authoring Guide

New page templates structure

Last update: October 27, 2026

Use these templates to start new pages quickly and consistently. They give you the right metadata, section order, and writing guidance for each page type, so you can focus on content instead of setup. This page also explains how to organize a page into concept and task blocks.

Start from a template templates

Don’t start a new page from a blank file. Copy the template that matches your page type. Each template includes the front matter (metadata), the section order, and guidance comments that explain how to fill it in.

If you are writing…
Copy this template
A documentation page (concept or task) with no embedded video
template-docs-only.md
A page that presents both a video and written documentation
template-docs-and-video.md
A page whose main content is a video, with a summary that links to the written steps
template-video-only.md
The first page of a workflow group in the TOC (introduces the group and links to the use case pages)
template-workflow-overview.md
A landing page made of cards for an application’s repository
template-landing-page.md
A “CX Enterprise Coworker in [Product]” learn page
template-cxo-learn.md

To use a template

  1. Copy the template file into the folder for your topic. Give it a descriptive, lowercase, hyphenated file name, such as create-an-email-campaign.md.
  2. In the front matter, delete the TEMPLATE ONLY comment line and the hide: true line. If you leave hide: true in place, the page is excluded from search and recommendations.
  3. Replace everything in [brackets], and delete any section you don’t need.
  4. Update the metadata: confirm that title and description follow the metadata requirements, and replace the product_v2, role_v2, level_v2, and topic_v2 values if they don’t fit your content. See Metadata and tagging.
  5. Delete the TEMPLATE GUIDANCE comment block before you commit the page.
  6. Add the page to your TOC.md file if it should appear in the table of contents.
NOTE
If a page needs a video embed, use template-docs-and-video.md so the video team and documentation team own separate sections. Don’t paste an embed into the docs-only or workflow overview templates.

Structure a page page-structure

Purpose. Organize a page into concept and task blocks that match how readers think about the problem—not by how much content you have or the order you learned the feature.

Information generally becomes more specific as a page or guide progresses:

  1. H1
  2. Introduction—what it is and why it matters
  3. Prerequisites (if needed)
  4. Important limitations
  5. Procedure
  6. Examples
  7. Reference

Patterns

  • Multipage: Parent concept page in the TOC; child pages are tasks.
  • Single page: One concept H1, then multiple task H2s, each with a short intro and steps.

Should

  • Give each section one job—explain what something is, help the reader do something, or let the reader look up a fact. Don’t bury explanation inside a procedure; explain the feature first, then let the procedure focus on the task.
  • Give each task H2 enough context before its numbered steps. If the heading already states the action and no extra context is needed, you can move directly to steps.
  • Put information where the reader needs it: prerequisites before the task, warnings before the risky step, a result with the step that produces it, definitions near first use, and optional details last.
  • Write headings and opening sentences so a section makes sense on its own—readers often land mid-page from search, a deep link, or an AI-generated answer, not from the top of the page.
  • Split off a new section or topic when a section’s purpose changes (explanation turns into a procedure, the audience changes, or a chunk is likely to be searched for on its own)—not just to make a long section shorter.

Quick test. Before publishing, ask: Can you state what each section does for the reader in one sentence? Would the section still make sense to someone who landed there directly?

See also — Concepts and tasks, Steps and bullet lists.

recommendation-more-help
authoring-guide-help-main-guide