> ## Documentation Index > Fetch the complete documentation index at: https://docs.synscribe.com/llms.txt > Use this file to discover all available pages before exploring further. # Contributing conventions > How to write, structure, and keep pages consistent on this site. 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 ``` docs/training/ ├── index.md ← home + learning paths ├── part-1-theory/ ← the Synscribe Way (why) ├── part-2-platform/ ← platform how-tos (how) ├── part-3-sops/ ← SOPs for running accounts at scale (AM-only) ├── _sources/ ← mined raw material (NOT published pages) ├── gap-register.md ← every ❓ needing Raymond, aggregated ├── video-shot-list.md ← videos still to record ├── JOURNAL.md ← build log (per milestone) ├── PLAN.md · GOAL.md · CONVENTIONS.md ← meta (not published pages) ``` 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) ```yaml theme={null} --- title: # shown in nav + as H1 source description: # for search + page subtitle part: 1 | 2 | 3 audience: all | am | self-serve # who this page is primarily for (default: all) video: # primary embedded video, if any status: draft | review | done # editorial state --- ``` ## 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: ``. > **For self-serve —** the quick version: ``. * Part 3 (SOPs) is `audience: am` throughout. ## Video embed slot Videos aren't in the repo. Use a consistent placeholder so a generator can render it and a missing video is obvious: ```md theme={null} > 🎥 **Video:** []() ``` If no video exists yet, leave a shot-list marker and add the page to `video-shot-list.md`: ```md theme={null} > 🎬 **Video planned:** . See the shot-list. ``` ## 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: ````md theme={null} ```text based on the latest transcript and review, draft up a strategy. suggest [N] keywords for this cycle and tag them '[cycle tag]'. ``` Pi drafts the strategy, proposes keywords, and tags them — then asks you to confirm before executing. ```` ## Markers * `❓ [needs Raymond: ]` — 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: ```md theme={null} # How to set up blog refiners in Synscribe Set up refiners on the Content Refiners page (`/app/refiners`), or ask Pi with the `refiner-management` skill. A refiner is a reusable rule that rewrites a draft (brand positioning, CTA, FAQ, TLDR); you configure them once per client and apply them in one pass. This is different from the evaluator, which gates content rather than editing it — see [Refiner vs evaluator](./2-7-4-refiner-vs-evaluator.md). > 🎥 **Video:** … ## Steps … ``` The Answer box is what a retrieval system extracts and an answer engine cites, so it must stand alone and be accurate. ### 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: ```yaml theme={null} task: setup | keywords | landing-pages | blog | publish | analytics | compliance | diagnose feature: refiners | lp-refiners | evaluator | keyword-eval | serp-cliff | pillars | product-bible | gsc | posthog | image-generator | press-release | link-building | seo-debug | fanout persona: all | am | self-serve intent: how-to | concept | reference | sop keywords: ["how to set up refiners", "blog post automation rules"] # target queries ``` ### 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].