ByteOr Docs Authoring Model

    ByteOr docs are Markdown-first. MDX is available because the site needs repeatable structure and a small number of high-legibility interactive surfaces, not because every page should behave like an app screen.

    Decision Rule

    Use the simplest form that preserves clarity

    Use plain Markdown for most pages: architecture explanations, operator procedures, API walkthroughs, and reference text that reads as prose.

    • Default to .mdx files but keep the content mostly Markdown syntax.
    • Use one H1, a short lead, and stable section hierarchy.
    • Keep diagrams, lists, tables, and code fences readable without custom UI.

    Directory Conventions

    Page content stays in docs/
    Routeable public content belongs in the normal docs tree and should stay readable as documents first.
    Reusable snippets live under underscore directories
    Create underscore authoring directories only when you actually need reusable fragments or page-local MDX helpers.

    Underscore Directories

    Use the following split only when a page really needs authoring-only helpers:

    • docs/_fragments/ for reusable MDX snippets or shared prose sections.
    • docs/_components/ for page-local MDX helpers that should not sit in the theme layer.
    • theme/components/ for true site-wide UI and layout primitives.

    If these directories are empty, remove them rather than keeping placeholder folders in the repo.

    Page Template

    Every public page should converge on the same skeleton.

    1. Frontmatter with title and description.
    2. One H1 that matches the page purpose.
    3. A short lead paragraph that tells the reader what problem the page solves.
    4. Predictable H2 sections for architecture, workflow, reference, or operations.
    5. Code fences with useful metadata and minimal inline styling noise.

    Markdown Pipeline

    Code Blocks

    • Keep language tags explicit.
    • Use wrapped code blocks by default.
    • Fold very long blocks globally unless a page specifically needs full-height code.

    Preview and Playground

    • Do not add a sandbox just to render code examples that already work as static snippets.
    • If a future page genuinely needs live preview, prefer an iframe-backed surface that loads the same docs theme stylesheet so Tailwind and shadcn primitives render identically to the rest of the site.
    • Keep preview surfaces narrow and page-specific rather than introducing a site-wide playground mode.

    Components and Surfaces

    Provenance
    Need the canonical source?
    Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.
    Source-of-truth modelRepo docs index