Write a wiki page

Write one useful page from checked sources. Keep claim titles and quoted voice. Do not invent facts to complete a page.

1. Choose the kind

Use title, description, group, terms, and sources for lore and systems. Copy a nearby page’s field shape.

Use one H1 per rendered view. Lore and system titles come from frontmatter; do not repeat them as body H1s. Skills include their own H1.

Lore and system directories are discovered without per-page registration. Skills are discovered too, but need a group in skillGroups in apps/site/scripts/generate-content.ts.

2. Write short prose

Lore and system pages use low prose, about 80% ASD-STE100 Simplified Technical English. This is a house style, not certification.

Before:

The schema is used by the handler in order to ensure that input is decoded before dispatch can take place.

After:

The handler decodes input with the schema before dispatch.

A schema defines accepted values and their runtime checks. A handler implements an action on the server.

Generation warns on sentences above 25 words and paragraphs above four sentences in lore and systems. It also warns on history wording, contrast hedges, and em dashes. Warnings show file:line, the count, and the limit. The generator prints a total too.

The check reads parsed prose, including list paragraphs. Style rules skip quoted spans, blockquotes, code, links, tables, and frontmatter. Length rules still count link labels. Warnings never fail the build. Fix new warnings or explain why they remain.

3. Use a visual when it explains something

Keep diagrams below 80 columns. Give each visual one or two nearby sentences. Add a What to notice line only when the point is not obvious from those sentences. Remove decorative visuals.

Write for a person first. Avoid hedged ‘X, not Y’ asides and narration about sources.

4. Quote code from its source

Follow Code snippets quote a pinned source14. Author Markdown fences, not <Code> elements.

Metadata accepts:

A small authored example may have a body:

```ts {2} title="answer.ts"
const answer = 42;
export { answer };
```

The highlight uses the inline example’s line numbers.

A source reference has an empty body. This fence45 quotes the shipped SHA check:

packages/code-snippets/src/scanner.ts · a646f7ff · The pin is forty lowercase hexadecimal characters
const validCommit = (value: string) => {
  for (let index = 0; index < value.length; index += 1) {
    const char = value.charAt(index);

    if (!(char >= "0" && char <= "9") && !(char >= "a" && char <= "f")) {
      return false;
    }
  }

  return value.length === 40;
};

at names the immutable revision. {189} uses the original file’s line number.

For a reference:

  1. Choose a registered repository id. The default is rat-stack.
  2. Choose a repository-relative path without traversal, empty segments, dots, or colons.
  3. Set at to a full 40-character lowercase commit SHA.
  4. Set lines to positive, ordered, non-overlapping inclusive ranges.
  5. Keep highlights inside the selected ranges.
  6. Remove all body text.

Configured fences show at most 25 source lines. This includes inline fences with metadata. Collapsed gaps do not count. Ordinary fences without metadata are not subject to this cap.

Explicit language wins. Otherwise, a referenced extension selects it. An unmapped extension or unlabelled inline fence defaults to Markdown.

svx maps to Markdown; txt maps to text. javascript is accepted explicitly. Unknown explicit languages fail; use text for uncoloured code.

Drift warnings compare selected pinned lines with HEAD. They do not replace the pin or fail the build. Review changes before updating a SHA.

Generation reads local Git objects offline. A shallow clone must contain each pin. Run pnpm sources:fetch as an explicit bootstrap when objects are missing. Template children need this once after repository creation.

Repair errors

Diagnostics print source path, line, tag, repository, file, SHA, ranges, and repair text. Example:

page.svx:7 [CodeUnknownKey] rat-stack:<inline>@<inline> lines=all; Unknown key bogus; use repo, path, at, lines or title.

Fix the fence at the first path and line. The remaining context describes the requested source.

Read packages/code-snippets/test/pipeline.test.ts and git.test.ts for these messages. Example numbers describe test fixtures.

CodeInvalidProps also reports “Pin at to a full 40-character lowercase commit SHA.” Use a SHA, not a branch or tag.

CodeBuildFailed collects formatted failures. Its message joins them with newlines; it adds no separate repair sentence. Fix every reported fence before emission.

Check the exact-message tests when diagnostics change. Do not present a paraphrase as an exact quote.

A linked entry has url, title, publisher, note, and accessed. Its kind defaults to linked.

An authorized recorded source uses kind: recording, title, recordedAt (ISO date), and note. It has no URL. Keep private recording links and identifiers out of public files. Both views show its title and date without a link.

The note says what the source supports. Recording entries do not supply deck references; add a checked public source for those.

Cite exact revisions for code. Keep sourced content within its evidence. Mark missing evidence rather than adding plausible claims.

6. Check components and disclosure

Use apps/site/scripts/component-registry.ts. Every component needs human and agent renderers. Read the agent view; do not assume a visual carries its meaning there.

Registry renderers in Mischief derive both views from one CodeSnippet model. Git and Shiki stay build-only. Ship page content as static assets. Keep it out of new Worker route handlers.

Hot pink is the only accent. Use it for at most one thing per screen, plus focus. Links, headings, tables, and tier cells never use pink.

Use plain class and id names. Avoid ad-like names such as ad-banner, advertisement, sponsored, or promo-banner.

Never name the email delivery partner or list vendor in public prose. Describe the job generically. Keep private paths, host names, credentials, and customer data out of pages and examples.

7. Finish

  1. Run pnpm install --frozen-lockfile before gates after any dependency change.
  2. Run pnpm --filter @rat-stack/site generate.
  3. Read all prose and source-drift warnings.
  4. Run pnpm turbo run check test build.
  5. Read the generated HTML view.
  6. Read the generated Markdown view.
  7. Verify one H1 per view.
  8. Compare each pinned excerpt with its Git object.
  9. Check glossary links, block references, citations, and the bibliography.
  10. Record checks and any explained warnings before committing.

Fix failures without weakening the fence: compiler checks, lint rules, and hooks that reject prohibited code and shortcuts. Verify deployment separately from the build.

Last changed 2026-10-27 in 49994c9. Source on GitHub. Change log.