Skip to main content

Guides

Route/authoring/guides PreviewScribe previewscribe

Guides are the narrative pages of a version — "Onboarding, authentication and error narratives live here rather than on any one operation." A guide belongs to one version of one API, is written in Markdown or MDX, moves through draft, review and published states, and keeps every revision. Guides is reached from the secondary navigation, the palette, or the README generator's link; it is not in the suite dropdown. Without a scope: "Choose a project and version to author its guides. A guide belongs to one version of one API."

The tabs​

TabWhat it is for
PagesCreate, place and reorder the guides in this version
EditThe source of the working revision
PreviewWhat a reader sees, rendered in a sandbox
ChecksLinks, headings, code blocks, assets and accessibility
HistoryRevisions, the diff against what is live, and rollback
AssetsAttached files and their text alternatives

Pages​

The navigation tree, each guide with a status pill (Draft, In review, Published, Archived) and Unpublished changes or Stale badges; Move up and Move down reorder it. Empty: "This version has no guides yet. Create one to start the onboarding, authentication or migration narrative it needs."

note

New guide switches to the Edit tab but does not yet create a guide on the server: the create call exists in the API client and is not wired to the button. Guides that exist in the version can be edited, published and rolled back.

Edit​

Title, Summary ("Shown in navigation, in search results and wherever this page is linked."), the Address slug, and the body, as Markdown or MDX. The Components palette inserts Callout, Steps, Step, CodeGroup, Tabs, Tab, Card, ApiRef, Badge and Figure. Save revision records a revision; until then "This buffer has changes that are not yet a revision."

Preview​

Rendered in a sandbox — "This preview is a sandbox. Links do not navigate, images are described rather than loaded…" An unsafe construct is refused with its code and line. The Search section shows what the page contributes to the site's search index; the hosted index itself arrives with the analytics backend.

Checks​

Findings marked Error, Warning or Note, grouped as Links, Headings, Code blocks, Assets and Accessibility, each with a line number.

History​

The diff Draft against the published revision, the revision list with · Live against the one readers see and an origin for each (Written, AI-assisted, AI draft, Imported), and Publish, Unpublish and Roll back to rN. An AI draft that has not been reviewed is refused at publish.

Assets​

Each attached file has a Text alternative or a decorative checkbox, and Detach file. There is no upload yet.

Stale guides​

A guide is marked Stale when a target it references is missing, the API changed after it was published, a newer draft exists, or it was published 180 or more days ago.

Rules​

  • A published version is frozen: "This version is published and its content is frozen… Create a new version to change what it documents."
  • Writes carry the revision they expect; a guide changed elsewhere is refused rather than overwritten.
  • Without the scribe flag: "Guides are part of Scribe, which is not enabled for this tenant."
  • When no documentation backend answers, the page shows worked-example guides and says so: "No documentation service answered, so these guides are worked examples rather than your content. Nothing you change here is saved."

Guides feed the README generator, which fills its sections from them.