Skip to main content
How every page in this training site is written, so the whole tree stays consistent and drops into a docs generator (Astro Starlight / Mintlify / etc.) later without a rewrite. Read this before adding or editing a page.

​
Structure

Page files are kebab-case.md, prefixed with their map number for ordering, e.g. part-2-platform/2-2-1-keyword-exploration.md.

​
Front-matter (every published page)

Keep sidebarTitle short and scannable. The title carries the full, question-shaped query for the H1 and search; the sidebar link just needs a compact label. Don’t duplicate the long title into the sidebar: title How to extract keywords from competitors doing programmatic SEO becomes sidebarTitle Extract keywords from competitors.

​
Audience tagging

Self-serve subscribers can do everything AMs can — the difference is discipline and standardization at scale, not gated features. So:
  • Default a page to audience: all and write it for everyone.
  • Where the guidance genuinely diverges, use an inline callout rather than forking the page:
    For AMs — the rigorous, standardized version: <checklist / cadence / quality gate>.
    For self-serve — the quick version: <the lighter path>.
  • Part 3 (SOPs) is audience: am throughout.

​
Video

If a Loom video is provided, EMBED it in the page — don’t just link it. Convert the share URL (loom.com/share/<ID>) to the embed URL (loom.com/embed/<ID>) and place the iframe right after the Answer box, before the first section:
Also put the share URL in the video: front-matter. Once it’s embedded, don’t leave a duplicate 🎥 text link. If no video exists yet, leave a shot-list marker and add the page to video-shot-list.md:

​
Real prompts

When the “how” is a prompt you send Pi, show the real (mined, anonymized) prompt in a fenced block, then say what Pi does with it. Placeholders in [brackets]. Example:

​
Markers

  • ❓ [needs Raymond: <question>] — an unverified claim; also add it to gap-register.md.
  • Never state an unverified platform behavior as fact. Ground claims in code/prod/SOP/video.
  • Never mention credits / credit units. Describe throughput in posts/pages/weeks.

​
Cross-linking

Use relative links between pages (../part-2-platform/2-2-1-keyword-exploration.md). Every Part 1 concept should link to the Part 2 page(s) that operationalize it, and every Part 3 SOP should link to the Part 2 how-tos it depends on. Extra rules for the how-to library:
  • Every how-to links up to its Part 1 concept (“why”), across to the next/previous task in the flow, and sideways to its sibling how-tos in the same feature cluster (e.g. all the refiner + evaluator pages link to each other).
  • Difference-explainer pages (“X vs Y”) link to both things they compare.
  • No orphans: every how-to must appear in the How-to index. A page not in the index is a bug.

​
How-to library conventions (GEO)

Part 2 pages are a library of short how-tos — each answers one “How do I do X with my software / my AI?” question, and each is written to be found and cited (by humans and by AI agents). Applies to Part 2 pages (intent: how-to); Part 1 stays conceptual, Part 3 stays procedural.

​
Question-shaped titles

A how-to page’s title and H1 are the literal search query, phrased as the task:
  • Good: “How to set up blog refiners in Synscribe”, “How to check if you can rank for a keyword”.
  • Not: “Refiners”, “Keyword evaluation”.
Keep the numeric filename (2-1-7-…) for ordering; the title carries the query. (Part 1 concept pages keep conceptual titles and answer “why”.)

​
The Answer box (first thing on every how-to page)

Right under the H1, before any section, put a 2–4 sentence direct answer — self-contained, no “read the next section first”. State what to do, name the surface (e.g. /app/refiners) and the Pi skill, and link onward. Steps and nuance follow below. Format:
The Answer box is what a retrieval system extracts and an answer engine cites, so it must stand alone and be accurate.

​
Followable steps

Write steps a reader can follow top-to-bottom without jumping around. When the “how” is a series of prompts you send Pi, weave each real prompt into the step where you send it: the instruction, then the prompt in a fenced block, then a one-line “what Pi does”, then the screenshot of the result. Don’t hive the prompts off into a separate section the reader has to cross-reference. Use numbered ### sub-headings for steps (a top-level fenced prompt inside a numbered list item breaks the list), which also surface each step in the on-page nav.

​
Generalize the example

Source material is usually one client’s case (e.g. an AI-video tool). Keep one concrete example for colour, but write the method so a reader in a different domain can map it onto their own: use [product] / [category] placeholders in prompts, keep domain-only nuance (e.g. “group video by style”) out of the general instructions, and if a point only applies to some readers (B2C vs B2B, say), fold it into a short note rather than the main step.

​
Extended front-matter (how-to pages)

In addition to the base fields, how-to pages carry facet tags so the How-to index can group them and so the library is machine-navigable:

​
The How-to index

part-2-platform/index.md is the How-to index (surfaced as its own nav tab). It lists every how-to three ways — by task, by feature, by persona — each row linking to the canonical page. It is a router, not a second copy: one source of truth per topic. Regenerate/curate it whenever a how-to is added.

​
GEO checklist (per how-to page)

  • Question-shaped title/H1 = the target query; Answer box first; keywords + intent set.
  • Every factual claim links to the product surface or the concept that backs it.
  • No credit language; straight quotes; MDX-safe.
The .md mirror + /llms.txt that make these pages agent-citable are generated by Mintlify’s hosted deploy, not mint dev (local returns 404). Realizing that GEO win needs the cloud deploy — tracked as a [DECIDE].