Skip to content

Speakeasy style sheet

A short document covering what we know to date about the style choices you should make for Speakeasy documentation and blog posts. Very much a work in progress.

Markup language

Speakeasy documentation and blog posts are written in MDX (.mdx files). You may encounter some Markdown (.md) files.

MDX (Markdown with JSX) uses the same formatting syntax for basic text elements as standard Markdown. This guide to basic Markdown syntax shows you how to format elements like headers, bold text, italic text, lists, and links.

Style specifics

The rules for style we highlight here are only those that deviate from the Ritza style guide or are specific to Speakeasy.

Heading capitalization

Speakeasy documentation uses sentence case for titles and section headings.

Backticks

  • In body text, place all references to code in backticks, including class names and description values.
  • Don't use backticks in titles, headings, or subheadings because they don't render well.
  • Don't put language names in backticks unless it's part of a code snippet:
  • ❌ In go, all types from all operations are collected into a global AcceptHeaderEnum type.
  • ✅ In Go, all types from all operations are collected into a global AcceptHeaderEnum type.

Code blocks

Speakeasy documentation uses Code Hike for code blocks.

  • Prefer code blocks to inline code for code snippets.
  • Prefer YAML to JSON for code snippets where possible to improve readability. For example, use YAML for all OpenAPI document examples.
  • Try to add a language to all code blocks. This helps with syntax highlighting.
  • Use the bash language for shell commands.
  • Terminal output can be highlighted by copying the output with control sequences (copy using iTerm2), then pasting the output to a code block and selecting the ansi language. This will render the output with the correct colors and formatting.
  • The ansi language isn't rendered as a Code Hike component. If you need to use the ansi language, use a standard code block.
  • The mermaid language is used for diagrams. This language is excluded from Code Hike rendering.
  • Use the <CH.Scrollycoding> component for long code blocks or code overviews. This component allows users to scroll through the code block.

UI element labels

Place all UI element labels like button text, menu items, tab names, section names, and page titles in bold.

Word choice

  • Prefer "create" over "generate" when referring to the Speakeasy functionality for producing SDKs.
  • Refer to Speakeasy-created SDKs as "SDKs" not "client SDKs".
  • Existing Speakeasy documentation uses both "auto-generate" and "autogenerate". We prefer "autogenerate".