Skip to main content

​
Style Guide

Applies to: All document types
Back to overview: Content Standards
This guide defines voice, tone, page structure, component usage, formatting, and linking conventions for all Aviatrix documentation. Individual doc type definitions reference this guide and note any type-specific restrictions or additions. For word choice and terminology, see the doc-style-guide skill (.claude/skills/doc-style-guide/terminology.md).

​
Voice and tone

Write in second person (“you”) throughout. Do not use first person (“we”, “I”, “our”). Use active voice and imperative mood for all procedure steps: “Click Save”, “Enter the gateway name”, “Select a subnet.” Do not write steps as observations (“The page displays…”) or suggestions (“You should click Save”). Do not use contractions. Write “do not” not “don’t”, “cannot” not “can’t”, “it is” not “it’s”. Avoid minimizing language. Do not use “just”, “simply”, “easy”, or “obviously” — these words dismiss difficulty and erode trust with readers who find the task hard. Write headings in imperative mood, not the gerund form: “Create a User”, not “Creating a User”.

​
Page structure

No H1 in the body. The title frontmatter field renders as the page H1. Do not add a # heading in the document body. Headings start at H2. Never skip heading levels — do not jump from H2 to H4 without an H3 in between. Headings use title case. Capitalize proper nouns, verbs, and adjectives. Lowercase articles and prepositions of four letters or fewer in the middle of a heading (a, an, and, the, of, to, for, in, on, with, by), unless the word is first or last in the heading. The sole exception is FAQ-style headings, which use sentence case with a trailing question mark: “How do I reset my password?” A heading must not immediately follow another heading or the page title with no body content between them. Add at least one sentence of introductory text before the next heading. Mintlify components do not require import statements. Use <Note>, <Tip>, <Warning>, <Info>, <Steps>, <Step>, <Tabs>, <Tab>, <Accordion>, <AccordionGroup>, <CodeGroup>, <Frame>, <Card>, and <CardGroup> directly in MDX without importing them.

​
Mintlify callout components

Use callouts sparingly. Every callout interrupts the reading flow — if used too frequently, readers learn to skip them. Rule of thumb: if removing the callout would cause a reader to make a mistake, use <Note> or <Warning>. If it just makes their life easier, use <Tip>. If it provides background that helps but isn’t necessary, use <Info>.

​
Structural components

​
<Steps> and <Step>

Use <Steps> for ordered procedures where sequence matters and each step is a meaningful, completable action. Every <Step> must have a title attribute.
Use <Steps> for any multi-step procedure where sequence matters. Do not nest <Steps> inside <Steps>.

​
<Tabs> and <Tab>

Use <Tabs> when the same task or information has meaningfully different implementations across modalities or environments. In Configuration Guides, this means UI / Terraform / API tabs. In Architecture documents, this means design variants. Always order tabs: UI first, then Terraform, then API. This ensures the most broadly applicable option is the default view.
Do not use <Tabs> to hide content that should be in separate sections or separate documents. If the content in each tab is longer than ~50 lines, consider whether separate documents are more appropriate. For Configuration Guides that combine a UI procedure with a Terraform procedure, follow Terraform integration in UI-based guides for the required tab titles, icons, step structure, and Examples sub-section.

​
<Accordion>

Use <Accordion> for optional supplementary content that most readers will skip — long parameter lists, advanced options, or troubleshooting details embedded in a reference page. Do not use it to hide required information or primary procedure steps.

​
<CardGroup> and <Card>

Use <CardGroup> for index and landing pages, and for the Key Components section of Solution documents. Each card should link to a distinct document or resource. Do not use <CardGroup> inside procedural guides — content should be linear and fully visible.

​
<Frame>

Wrap all embedded images in <Frame>. This provides consistent styling and layout.

​
Text formatting

​
Bold

Bold is used exclusively for UI element names — buttons, field names, menu items, toggle labels, tab names — exactly as they appear in the product interface.
  • Correct: Click Save, set Gateway Size to C5 Large, navigate to Settings
  • Incorrect: This is important (use a callout instead), the gateway (not a UI element)

​
Code formatting

Use inline code for:
  • CLI commands and flags: aviatrix-cli gateway list
  • File paths and filenames: docs.json, /etc/aviatrix/
  • Code values and variable names: true, vpc_id
  • API endpoints and parameters: /v1/api/gateway
  • Terraform resource names: aviatrix_gateway
Use code blocks for multi-line content: CLI output, Terraform HCL, API request/response examples, configuration file contents. Always specify the language for syntax highlighting:
Common language tags: hcl, bash, python, json, yaml, text (for unformatted output).

​
Italics

Use italics sparingly — for introducing a defined term on its first use, or for titles of documents and products referenced in prose. Do not use italics for emphasis; use a <Note> callout or restructure the sentence. Use the > separator for CoPilot navigation paths, with a space on each side of the arrow. Bold the full path when it directs a click — never italicize it: CoPilot > Cloud Fabric > Gateways > + Gateway
  • Cap navigation paths at 3 items. If the real path is longer, shorten it after first use (see below) rather than listing every intermediate level.
  • Omit the product name (“CoPilot”, “Controller”) from the path unless the product name itself is a clickable element in that step.
  • Use the full path on first use, then switch to a shortened form for later references in the same document (for example, first use CoPilot > Cloud Fabric > Gateways, later just Gateways).

​
Action verbs

Use these verbs consistently for UI interactions: Do not use “hit”, “press” (for non-keyboard actions), “choose”, or “go to” in place of these.

​
Product name spelling

  • CoPilot — not “Copilot”, “Co-Pilot”, or “copilot”
  • Controller — always capitalized

​
Numbers

Use numerals for 0 and for any value above 9. Spell out one through nine, unless the same sentence also contains a number above 9 — in that case, use numerals for both (for example, “Configure 3 subnets across 12 availability zones”).

​
Dates

Write dates as DD Month YYYY, for example “11 May 2025”.

​
Time

Write times as H AM/PM (TZ), for example “2 AM (PST)”.

​
IP addresses in examples

Use only RFC 5737 test-net ranges for example IPv4 addresses: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24.

​
URLs

Show the bare address only — omit https://www., for example http://aviatrix.com.

​
Oxford comma

Use the Oxford comma in any list of three or more items: “Aviatrix offers visibility, security, and control across cloud networks.”

​
Lists

Use ordered lists (1., 2., 3.) when sequence matters — procedure steps, ranked options. Use unordered lists (-) when sequence does not matter — feature lists, requirements, options of equal priority. Keep list items parallel in structure. If one item is a complete sentence, all items should be complete sentences. If one item is a noun phrase, all items should be noun phrases. Do not use lists for two-item comparisons — write them as prose. Do not create lists longer than ~8 items without subgrouping under H3 headings.

​
Tables

Use tables for structured data where the relationship between columns matters: field reference tables, version compatibility matrices, issue tracking, option comparisons. Use three-column tables for field documentation: Field | Description | Notes. Do not use tables for simple lists that have only one meaningful column, or for content that is better expressed as prose.

​
Images and diagrams

  • Store images in the nearest images/ directory relative to the document file
  • File names: kebab-case, descriptive, no spaces (e.g., transit-gateway-topology.png)
  • Format: SVG (preferred for diagrams), PNG (for screenshots), minimum 1200px wide
  • Always wrap images in <Frame>
  • Always include descriptive alt text — describe the content, not the format:
    • Good: "Diagram showing a hub-and-spoke topology with one Transit Gateway and four Spoke Gateways across two cloud regions"
    • Weak: "Architecture diagram" or "Screenshot"
  • Include a caption (italicized text immediately below the <Frame>) for diagrams
Screenshot annotation:
  • Border: gray, 1pt
  • Highlight rectangles: red, 4pt weight, no shadow
  • Arrows: red, 4pt, single triangular head, rectangular end, no shadow
  • Numbered-step circles: 40x40px, red, with the number in white Arial regular — pair each circle with an explanatory numbered list below the image rather than embedding text callouts directly in the screenshot
Diagram convention:
  • Use Lucidchart for architecture and topology diagrams
  • Balance accuracy against simplicity — omit detail that doesn’t serve the reader’s task
  • Use Aviatrix brand colors and icons (see the Marketing SharePoint for the current icon and color set)
Use relative paths for all internal links. This ensures links work in local preview and across environments.
Do not use absolute URLs for internal links. Do not use bare URLs as link text — write descriptive link text that tells the reader what they will find. External links (Terraform Registry, cloud provider documentation, GitHub) use absolute URLs and should open in the same tab unless there is a specific reason to open a new tab. Do not link to legacy.docs.aviatrix.com. Migrate any references to the current documentation path.

​
Reusable content (snippets)

The snippets/ folder at the repository root contains reusable MDX content blocks. Use snippets when the same content — a warning, a prerequisite list, a standard note — appears in three or more documents and must be kept in sync. When to create a snippet:
  • The content is identical (or near-identical) across multiple documents
  • The content is likely to change and needs to be updated everywhere simultaneously
  • The content is a standard boilerplate (e.g., “Before you begin, ensure you have Controller version 8.2 or later”)
When not to use a snippet:
  • The content needs slight customization per document (write it inline instead)
  • The content appears in only one or two places (duplication is acceptable at that scale)
Naming convention: snippets/[area]/[descriptive-name].mdx — for example, snippets/prerequisites/controller-version.mdx. Import and use in MDX:
When updating a snippet, verify the change is appropriate for all documents that import it before committing.