Writing and structure

Writing and structure

This page is for contributors adding or revising published documentation. Keep each page focused on one responsibility and prefer the simplest Starlight primitive that makes the content easier to scan.

Start with the audience and page type

• users/ explains how to build and operate a FrameKit application.
• contributors/ explains how to change and verify the FrameKit repository.

Choose one primary page type:

• Tutorial or guide: get the reader through a task with only the details required to complete it.
• Concept: explain how a part of FrameKit works and why it exists.
• Reference: keep complete command, configuration, API, and file contracts.
• Troubleshooting: diagnose a symptom and point to the owning workflow or reference.

Do not turn index pages into copies of the sidebar. Use them to expose a small number of high-value starting points.

Prefer built-in Starlight components

Plain Markdown remains the default. Use MDX when a built-in component makes a workflow materially clearer:

• Steps for procedures with a meaningful order.
• Tabs for equivalent alternatives such as pnpm and npm. Use the same syncKey="package-manager" so the reader’s choice persists.
• FileTree for repository and project layouts instead of ASCII trees.
• LinkCard and CardGrid for short landing pages and task entrypoints.
• Starlight asides (:::note, :::tip, :::caution) for information that should stand apart from the main flow.
• Expressive Code title="src/file.ts" metadata when a code block represents a real file.

Do not add a custom component when a built-in Starlight component already expresses the same structure.

Keep guides short

A guide should contain the shortest supported path to the result. Move exhaustive switches, environment-variable contracts, generated-file details, and command behavior to Reference, then link to the owning reference page.

This avoids maintaining the same technical contract in several places and keeps getting-started pages readable.

Use current sources first

Verify published claims against the current repository in this order:

1. package manifests and public exports or binaries;
2. implementation and tests under the owning workspace;
3. the canonical generated-consumer template; and
4. current first-party integration where it demonstrates the behavior.

Legacy pages outside the published tree can reveal migration topics, but they are not authority over current code. Docs/Plans/ records work coordination, not product behavior. Do not copy historical commands or describe unsupported surfaces just because an older page mentions them.

Add or revise a page

Use .md for plain Markdown and .mdx when importing Starlight components:

apps/docs/src/content/docs/en/<audience>/<area>/<slug>.md
apps/docs/src/content/docs/en/<audience>/<area>/<slug>.mdx

Use concise frontmatter and avoid repeating the page title as a manual # heading unless the layout specifically requires it.

Keep repository paths, package names, commands, routes, and imports exactly as they exist in current sources. English links use /en/; Spanish links use /es/.

Do not edit generated output such as apps/docs/dist/ or apps/docs/.astro/.

Sidebar and localization

A content file has a route but may not be visible in the sidebar. Update apps/docs/astro.config.mjs when navigation changes. Prefer autogenerated directory groups where the content hierarchy already expresses the structure, and collapse reference-heavy groups that do not need to stay open by default.

English and Spanish published routes should remain in parity. When one locale changes, update its equivalent page in the same change unless there is an explicit localization plan saying otherwise.

Maintain skills from their source

Edit skills only under Docs/skills/, then synchronize them:

pnpm sync:skills

Never edit .agents/skills/ or packages/create-framekit/template/.agents/skills/ directly.

Verify documentation changes

Run:

pnpm --filter docs build

Then check the rendered routes, sidebar placement, internal links, synchronized package-manager tabs, and technical claims against current source. A successful build proves the site compiles; it does not prove a stale claim is correct.