Skip to content
Docs-as-Code Blueprint

Writing & Formatting in Sveltia

Creating clear, accessible documentation requires a balance of clean typography, structured formatting, and scannable page design. In Sveltia CMS, you can format your writing using either visual toolbar buttons or standard Markdown keyboard shortcuts.

Daily Formatting Toolbar Shortcuts

Section titled “Daily Formatting Toolbar Shortcuts”

When composing in Rich Text Mode, the top editor toolbar provides one-click access to standard styling controls:

Bold & Italic

Use Bold (Cmd+B / Ctrl+B) sparingly to highlight UI elements, buttons, or critical keywords. Use Italics (Cmd+I / Ctrl+I) for emphasis or book titles.

Headings (H2, H3, H4)

Select text and choose Heading 2 or Heading 3 from the format dropdown. The page’s main title is already H1, so start your document sections with H2 (##).

Bulleted & Numbered Lists

Create unordered bullet lists for item catalogs, and numbered lists for strict sequential procedures.

Blockquotes

Click the quote icon to indent citations or notable excerpts. For warnings and tips, prefer our custom <Aside> component instead.

Formatting Code & Technical Variables

Section titled “Formatting Code & Technical Variables”

Technical documentation frequently refers to file names, configuration keys, terminal commands, and code snippets. Distinguishing between inline code and multi-line code blocks is crucial:

Use for short technical terms inside running sentences.

  • When to use: File paths (e.g., astro.config.mjs), environment variables (GITHUB_TOKEN), keyboard shortcuts (Cmd+K), or CLI flags (--help).
  • How to format: Highlight the word and click the Inline Code (<>) icon in the toolbar, or wrap the term in single backticks: `code`.
  • Example in prose: “Open the .nvmrc file and verify that the version string is set to 24.”

Headings and Page Hierarchy

Section titled “Headings and Page Hierarchy”

Search engines and screen readers rely on strict heading hierarchies to navigate content. Follow these structural rules:

# Page Title (Automatically generated from the frontmatter 'title' field)


## Major Section (H2)
Introductory paragraph explaining the section concept.


### Subsection (H3)
Detailed breakdown of a specific subtask.


#### Deep Dive or Edge Case (H4)
Only use when dividing a complex subsection further.

Writing Dos and Don’ts

Section titled “Writing Dos and Don’ts”

To ensure our entire masterclass maintains a polished, cohesive editorial voice:

DO: Use Active Voice

Write “Click Save to commit changes” instead of “Changes are saved by clicking the button.”

DON'T: Hardcode Raw HTML

Avoid inserting raw HTML tags like <div style="..."> or <font>. Sveltia and Starlight provide built-in components that handle styling responsively.

DO: Write Descriptive Link Text

Link meaningful phrases like “read the Voice and Tone Guide” rather than “click here”.

DON'T: Overuse Bold Text

If everything is bolded, nothing stands out. Reserve bold text strictly for UI labels, buttons, and high-impact keywords.

Editorial Style & Standards Alignment

Section titled “Editorial Style & Standards Alignment”

Formatting is only the container; the clarity of the prose matters just as much. Consult our official editorial guides when polishing your drafts:

Word List & Terminology

Our authoritative dictionary for tech terminology, capitalization, acronyms, and AP Style exceptions. Read the Word List.

Grammar & Mechanics Contract

The definitive contract for punctuation, title capitalization, em-dashes, and Oxford commas. Read Grammar & Mechanics.

Voice, Tone & Accessibility

Principles for writing empathetic, approachable, and universally accessible technical guides. Read Voice, Tone & Accessibility.

Expressive Code Reference

Advanced code block features, including multi-line selections, file titles, and terminal diffs. Explore Expressive Code.