Style Guide

Target audience: Contributors and Maintainers Goal: Ensure consistent, high-quality documentation across all StageX content.

Introduction

Consistency across documentation reduces cognitive load for readers and prevents ambiguity. This guide codifies the conventions used in StageX documentation, covering frontmatter format, heading hierarchy, terminology, cross-referencing, code block style, and diagram conventions. Following these standards ensures that every page -- whether tutorial, how-to guide, reference, or explanation -- reads as part of a unified body of work rather than a collection of independently authored documents.

Target Persona Tagging

Every page tags its target audience in the tags frontmatter field using one or more of the following personas:

Rules for tagging:

• Assign 1-3 tags per page. Most pages need only 1-2.
• developer is the default for tutorials and how-to guides.
• maintainer is the default for contributing and reference pages.
• security-auditor and evaluator are primarily used for explanation docs but may apply to reference pages.
• Tags go in the YAML frontmatter as a comma-separated, lowercase list.

Heading Hierarchy

Use a strict hierarchical heading structure with no level skipping:

# Title                  -- One H1 per page, matches frontmatter title
## Section               -- Major divisions
### Subsection           -- Within sections
#### Detailed           -- Deeper only when necessary

Rules:

• Only one # H1 per page. The title heading must match the title field in the frontmatter.
• Do not skip levels. Never go from ## to #### without a ### in between.
• Keep heading text concise. Headings are signposts, not summaries.
• Use sentence case. Capitalize the first word and proper nouns only.
• Avoid headings with code or backticks unless referencing a specific tool or filename.

Frontmatter Conventions

Every documentation page must begin with YAML frontmatter containing three fields. Example:

---
title: "Quick Start: Your First Reproducible Build"
description: "Build a simple Rust binary with StageX and verify it builds reproducibly."
tags: developer
---

Rules:

• title: In double quotes, sentence case. Must match the # H1 heading on the page. Should match the nav title in zensical.toml.
• description: 15-25 words. Informative, enterprise tone. Describes what the user will accomplish or learn, not what the page is about. Avoid "This page covers..." or "A guide to...".
• tags: Comma-separated, lowercase. One or more of the four persona tags.
• No trailing whitespace on any line.
• No tabs inside the frontmatter.

Code Block Style

Always specify a language tag after the opening triple backticks. Use the following conventions:

Rules:

• Always specify a language tag. Never use bare triple backticks.
• Prefer --8<-- snippet includes for blocks over 30 lines. Use pymdownx.snippets with paths relative to the docs/ root. See existing examples in docs/how-to/nodejs-app.md and docs/how-to/python-app.md.
• Use $ prefix in console blocks for commands the user should type. No prompt prefix in bash blocks (these appear in Containerfile RUN instructions).
• Keep lines under 100 characters in code blocks where possible.

Cross-Reference Linking

Use relative paths for all cross-references. Never use absolute URLs for internal links.

[Link Text](../path/to/page.md)

Rules by quadrant:

Every page must have a "See Also" or "Next Steps" section at the bottom with 2-5 links.

Additional guidelines:

• Use descriptive link text. "Quick Start" is clearer than "here".
• Check anchor links against MkDocs slug rules. MkDocs strips special characters (+, ., :) from heading anchors. Verify with zensical build before committing.
• Include at least 2 different quadrants in the See Also links where possible.

Terminology and Naming Conventions

Use these standardized terms throughout all documentation:

Package names in prose: lowercase, hyphenated. When referring to a specific package directory, use monospace: packages/pallet/rust/.

File Naming Conventions

• All lowercase. No camelCase or PascalCase.
• Use hyphens to separate words, never underscores.
• Match nav titles to filenames. "Quick Start" becomes quick-start.md. "Build a Rust Application" becomes rust-app.md.
• Example project files go in docs/how-to/examples/ with subdirectories per project (e.g., nodejs-feedmix/server.js).
• Snippet files use their original extension (.py, .js, .rs) -- they are real source files, not markdown.

Diagram Guidelines

Use Mermaid.js for all diagrams. Mermaid renders natively with Zensical via the pymdownx.superfences custom_fences configuration.

graph TB
    A[Concept A] --> B[Concept B]
    B --> C[Concept C]

Rules:

• Fence with triple backticks and mermaid language tag.
• Keep diagrams simple -- maximum 15 nodes. Complex diagrams should be split into multiple sub-diagrams.
• Use subgraphs for grouping related concepts. Label each subgraph clearly.
• Use descriptive node labels. Labels must be understandable without reading the surrounding prose.
• Use consistent colors via style directives. Reserve orange for the hex0 seed, yellow for Stage 0, blue for Stage 1, and green for Stages 2-3 (see docs/tutorials/bootstrapping-journey.md for the canonical color scheme).
• Test rendering with zensical build -- Mermaid errors appear as blank boxes in the browser.

Pull Request Conventions

All commits follow the Conventional Commits format:

type(scope): description

Scopes match documentation quadrants:

Where a change spans multiple quadrants or does not fit a specific quadrant, omit the scope.

Reference relevant session IDs where applicable (e.g., docs(session): #18).

See Also Format

Every page must end with a "See Also" or "Next Steps" section. Use the following format:

• [Page Title](../path/to/page.md) -- Brief description of what the reader will find
• [Another Page](../path/to/page2.md) -- Brief description of what the reader will find

Rules:

• Precede with a --- horizontal rule for visual separation from the preceding content.
• Use a ## heading: ## See Also or ## Next Steps. Use "Next Steps" for tutorials that have a natural progression; use "See Also" for all other pages.
• Include 2-5 links as a bullet list.
• Each link follows the format [Title](../path/page.md) -- brief description using an em dash.
• Include at least 2 different quadrants where possible. For example, a how-to guide should link to at least one tutorial and one reference page.
• Keep descriptions short (5-15 words). The description should explain what the reader will find, not restate the page title.

See Also

• Contributor Guide — Workflow for reporting issues, submitting changes, and opening PRs.
• Reference: Package.toml Format — Full reference for the package metadata format.