Authoring

Content Authoring

Create, structure, and maintain wiki pages with consistent metadata.

All wiki content is authored as markdown files in content/.

This guide is intentionally longer than the rest of the wiki so you can use it as a practical editorial playbook instead of a short checklist.

Authoring flow

  1. Create a new .md file under content/.
  2. Add frontmatter fields (title, section, order, and optional fields).
  3. Write concise content with meaningful headings.
  4. Link related pages using /wiki/... paths.
  5. Run pnpm build to validate output.

Working model

Write each page as if a developer will land there directly from search, not from your intended reading order.

That means each page should include:

  • a short opening paragraph that defines the topic,
  • one clear promise of what the reader will learn,
  • actionable sections with examples or commands,
  • links to where the reader should go next.

When you follow that pattern, pages remain useful in isolation while still feeling connected as part of a broader wiki.

Good defaults

  • Keep each page focused on one topic.
  • Use short introductions before long lists.
  • Prefer internal links over repeated explanations.
  • Use draft: true for pages that are not ready.

Length guidance

  • Aim for roughly 300 to 900 words per page for fast scanning.
  • If a page grows beyond about 1200 words, split it into 2 focused pages.
  • Keep sections compact; 3 to 6 headings is usually enough for one topic.
  • Move deep examples into dedicated pages and link them from the overview.

How to split large topics

When a page becomes too long, do not split by arbitrary word count only. Split by intent.

Good split patterns:

  • Concept vs execution: one page explains why, another explains how.
  • Overview vs reference: one page gives the mental model, another is a lookup table.
  • Beginner vs advanced path: one page covers defaults, another covers edge cases.

Example for this project:

  • content-authoring: process and standards.
  • frontmatter-reference: strict field reference.
  • internal-linking: routing conventions.

This keeps each page focused and prevents readers from scrolling through unrelated sections.

Section design

For technical docs, section quality matters more than total length.

Use this structure for most pages:

  1. Context: one paragraph with the scope.
  2. Main steps: ordered list or short blocks.
  3. Pitfalls: what usually goes wrong.
  4. Verification: how to confirm it worked.
  5. Next links: where to continue.

Avoid long unbroken prose. Favor short paragraphs, grouped bullets, and explicit commands.

Writing style for this repo

Instant Wiki is performance-focused, so the writing style should mirror that philosophy:

  • direct wording,
  • no filler marketing copy,
  • examples that map to real files,
  • clear tradeoffs when there are alternatives.

Prefer concrete wording:

  • Better: “Run pnpm build and confirm all budgets pass.”
  • Worse: “Make sure everything is optimized before release.”

Prefer scoped claims:

  • Better: “Search index is loaded only when the overlay is opened.”
  • Worse: “Search is always instant and lightweight.”

Linking strategy

Links are a navigation system, not decoration.

Use links to prevent repetition:

  • If a paragraph starts re-explaining a concept already documented, replace most of it with a link.
  • If two pages share setup steps, centralize setup on one page and link to it.
  • If a page depends on previous knowledge, add a “Read this first” line near the top.

Useful link points:

  • after the intro,
  • before advanced sections,
  • inside checklists,
  • in the final “next” paragraph.

Examples and code snippets

Use snippets when they reduce ambiguity.

Good use cases:

  • frontmatter examples,
  • command sequences,
  • tiny config fragments,
  • expected output shape.

Avoid snippets that are too long to scan quickly. If a snippet exceeds what can be read in a few seconds, move it to a dedicated page or summarize the important part.

Editorial quality checklist

Before finalizing a page, quickly verify:

  • The title describes one clear topic.
  • The intro defines scope in 2-4 lines.
  • Headings are meaningful and not generic.
  • At least one internal link connects this page to related pages.
  • Commands are copy-paste ready.
  • Route references use /wiki/....
  • The page has no stale terminology from previous project states.

Maintenance cadence

Wiki quality drops when pages are never revisited.

A lightweight cadence that works well:

  • After major feature changes: update affected pages immediately.
  • Weekly: review newly added pages for consistency.
  • Monthly: check long pages for splitting opportunities and dead links.

If you use the updated field, reserve it for meaningful edits rather than tiny typo fixes.

Anti-patterns to avoid

  • Giant pages that mix setup, concepts, FAQ, and reference in one file.
  • Empty pages with placeholders that should be drafts.
  • Repeated “what is this project” intros across many pages.
  • Broken internal links due to renamed slugs.
  • Performance advice that does not map to current scripts or files.

When in doubt, optimize for clarity and maintainability over volume.

If you are adding many pages in one pass, run pnpm validate:wiki before pnpm build to catch structural issues early.

Type at least 2 characters.