> ## Documentation Index > Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt > Use this file to discover all available pages before exploring further. # Style guide # Style Guide > **Applies to**: All document types\ > **Back to overview**: [Content Standards](index.md) 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 ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, and `` 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. | Component | Use when | Do not use for | | - | - | - | | `` | Information the reader genuinely needs that does not fit in the prose — a constraint, a behavioral nuance, or a dependency | General context or introductory information that belongs in the body text | | `` | An optional shortcut, alternative approach, or efficiency hint that improves the experience but is not required | Required steps or critical information — use `` instead | | `` | An action that is irreversible, destructive, causes service interruption, or has a security consequence | Anything that is merely inconvenient or that can be undone easily | | `` | Neutral contextual information that supplements the main content without being critical | When `` would be more appropriate — `` is for lower-stakes context | **Rule of thumb**: if removing the callout would cause a reader to make a mistake, use `` or ``. If it just makes their life easier, use ``. If it provides background that helps but isn't necessary, use ``. *** ## Structural components ### `` and `` Use `` for ordered procedures where sequence matters and each step is a meaningful, completable action. Every `` must have a `title` attribute. ```mdx theme={null} Navigate to **CoPilot > Cloud Fabric > Gateways** and click **+ Gateway**. Enable the **HA Gateway** toggle and select a subnet in a different availability zone. ``` Use `` for any multi-step procedure where sequence matters. Do not nest `` inside ``. ### `` and `` Use `` 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. ```mdx theme={null} ... ... ``` Do not use `` 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](guides/configuration-guide.md#terraform-integration-in-ui-based-guides) for the required tab titles, icons, step structure, and Examples sub-section. ### `` Use `` 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. ### `` and `` Use `` 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 `` inside procedural guides — content should be linear and fully visible. ### `` Wrap all embedded images in ``. This provides consistent styling and layout. ```mdx theme={null} ![CoPilot Gateway configuration panel showing the Gateway Size dropdown](../images/gateway-config.png) ``` *** ## 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: ```` ```hcl resource "aviatrix_gateway" "transit" { ... } ``` ```` 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 `` callout or restructure the sentence. ### Navigation paths 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: | Action | Verb | | - | - | | Pressing a button | Click | | Choosing from a list or set of options | Select | | Typing into a field | Enter | | Activating a toggle | Turn on / Turn off | | Checking a checkbox | Select | | Moving to a location in the UI | Navigate to | 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 `` * 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 ``) 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) *** ## Links Use relative paths for all internal links. This ensures links work in local preview and across environments. ```mdx theme={null} See [Configuration Guide](../guides/configure-transit-gateway.mdx) for implementation steps. ``` 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:** ```mdx theme={null} import ControllerVersionNote from "/snippets/prerequisites/controller-version.mdx"; ``` When updating a snippet, verify the change is appropriate for all documents that import it before committing. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.