Docs StyleCopy Anchor Link

Use this guide for NautilusTrader documentation style and writing practices.

The Markdown Style guide is the shared baseline for Markdown syntax and formatting, and .markdownlint.jsonc enforces its mechanical subset. This guide covers what is specific to NautilusTrader documentation rather than repeating that baseline.

General principlesCopy Anchor Link

• Prefer simple structure and concise, readable prose.
• Use consistent conventions, style, and patterns.
• Write for users of varying technical backgrounds.

Documentation typesCopy Anchor Link

Most pages should fit one of four types (Divio documentation system). Mixing types in a single page makes it harder to read and harder to maintain.

Two sections are exceptions:

• getting_started/ combines tutorial-style walkthroughs with setup instructions for onboarding.
• integrations/ pages combine reference (capabilities, symbology) with how-to content (setup, configuration). Thus, each venue page is self-contained.

Standalone how-to content that is not venue-specific belongs in how_to/.

Choosing the right typeCopy Anchor Link

• Does your page walk a newcomer through a learning experience? Tutorial.
• Does it answer "How do I...?" for someone who already knows the system? How-to guide.
• Does it explain why something works the way it does? Explanation.
• Does it list classes, config fields, enums, or capabilities? Reference.

A tutorial says "do this, then this, then this." The author picks the path. A how-to guide says "here is how to achieve X." The reader already knows they want X. Keep these distinct:

• Tutorials should not assume prior knowledge.
• How-to guides should not teach background concepts.

When one type needs to reference another, link to it instead of inlining. For example, a how-to guide that configures LiveNodeConfig should link to the API reference for field definitions rather than listing them again.

Language and toneCopy Anchor Link

• Use active voice when possible ("Configure the adapter" vs "The adapter should be configured").
• Write in present tense for describing current functionality.
• Use future tense only for planned features.
• Avoid unnecessary jargon. Define technical terms on first use.
• Be direct and concise. Avoid filler words like "basically", "simply", "just".
• Use parallel structure in lists. Keep grammatical patterns consistent across items.

Markdown tablesCopy Anchor Link

Table syntax, pipe alignment, and delimiter padding follow the Markdown Style guide.

Notes and descriptionsCopy Anchor Link

• All notes and descriptions should have terminating periods.
• Keep notes concise but informative.
• Use sentence case (capitalize only the first letter and proper nouns).

ExampleCopy Anchor Link

| Order Type             | Spot | Margin | USDT Futures | Coin Futures | Notes                   |
| ---------------------- | ---- | ------ | ------------ | ------------ | ----------------------- |
| `MARKET`               | ✓    | ✓      | ✓            | ✓            |                         |
| `STOP_MARKET`          | -    | ✓      | ✓            | ✓            | Not supported for Spot. |
| `MARKET_IF_TOUCHED`    | -    | -      | ✓            | ✓            | Futures only.           |

Support indicatorsCopy Anchor Link

• Use ✓ for supported features.
• Use - for unsupported features (not ✗ or other symbols).
• When adding notes for unsupported features, emphasize with italics: *Not supported*.
• Make unsupported notes specific when the reason matters: use *Not supported by <venue>* for venue gaps, or *Not currently implemented* for adapter gaps.
• Leave cells empty when no content is needed.

Code referencesCopy Anchor Link

Inline code and fenced code blocks follow the Markdown Style guide.

When referencing code locations, use file_path::function_name or file_path::ClassName rather than line numbers, which become stale as code changes.

HeadingsCopy Anchor Link

Heading style, case, and hierarchy follow the Markdown Style guide: title case for the page heading, sentence case below it.

NautilusTrader makes one exception for index.md pages: headings and navigation links that name individual documents use the target document's exact H1 title, including its capitalization. General section headings retain sentence case.

Always capitalize proper nouns regardless of heading level (product names, technologies, companies, acronyms).

ListsCopy Anchor Link

List markers, ordering, and indentation follow the Markdown Style guide.

End list items with periods when they are complete sentences.

Links and referencesCopy Anchor Link

Link text, link style, and images follow the Markdown Style guide.

Reference external documentation when appropriate.

Technical terminologyCopy Anchor Link

• Base capability matrices on the Nautilus domain model, not exchange-specific terminology.
• Mention exchange-specific terms in parentheses or notes when necessary for clarity.
• Use consistent terminology throughout the documentation.

Examples and code samplesCopy Anchor Link

• Provide practical, working examples.
• Include necessary imports and context.
• Use realistic variable names and values.
• Add comments to explain non-obvious parts of examples.

AdmonitionsCopy Anchor Link

Use admonition blocks to highlight important information:

Avoid overusing admonitions. Too many diminish their impact.

MDX componentsCopy Anchor Link

The docs site (fumadocs) provides built-in MDX components available in all .md files. No imports are needed.

TabsCopy Anchor Link

Use tabs for language-specific or variant content. List Rust before Python so Rust is the default (left-most) tab.

For code examples, add tab="..." to consecutive fenced code blocks:

\`\`\`rust tab="Rust"
let params = Params::from([("close_position", true.into())]);
\`\`\`

\`\`\`python tab="Python"
strategy.submit_order(order, params={"close_position": True})
\`\`\`

For tables or other content, wrap each variant in <Tabs> and <Tab>. The instrument Fields tables use this so each language shows a single type column instead of side-by-side Rust and Python columns. Leave a blank line above and below the inner content so the Markdown renders.

<Tabs items={["Rust", "Python"]}>
<Tab value="Rust">

| Field           | Type           | Required/default | Notes                   |
| --------------- | -------------- | ---------------- | ----------------------- |
| `instrument_id` | `InstrumentId` | Required         | Stored as `id` in Rust. |

</Tab>
<Tab value="Python">

| Field           | Type           | Required/default | Notes |
| --------------- | -------------- | ---------------- | ----- |
| `instrument_id` | `InstrumentId` | Required         |       |

</Tab>
</Tabs>

StepsCopy Anchor Link

Use Steps and Step for sequential procedures.

<Steps>
<Step>
Configure the adapter.
</Step>
<Step>
Start the trading node.
</Step>
</Steps>

AccordionsCopy Anchor Link

Use Accordions and Accordion for collapsible content.

<Accordions>
<Accordion title="Advanced configuration">
Content here.
</Accordion>
</Accordions>

FilesCopy Anchor Link

Use Files, Folder, and File for directory tree visualizations.

<Files>
<Folder name="src" defaultOpen>
<File name="main.rs" />
<File name="lib.rs" />
</Folder>
</Files>

CardsCopy Anchor Link

Use Cards and Card for linked content grids.

<Cards>
<Card title="Getting started" href="/latest/getting_started" />
<Card title="Concepts" href="/latest/concepts" />
</Cards>

TypeTableCopy Anchor Link

Use TypeTable for parameter or type documentation tables.

API documentationCopy Anchor Link

• Document parameters and return types clearly.
• Include usage examples for complex APIs.
• Explain any side effects or important behavior.
• Keep parameter descriptions concise but complete.