Nautilus Trader - Documentation Style Guide

Low-priority reference page. This captures the Nautilus project’s internal documentation conventions (Divio four-type model, MDX components, heading case, table style, line wrap). It only matters to Cortana if we ever upstream the UW adapter or contribute documentation back to the Nautilus repo. Cortana’s own brain pages live in ~/brain/ and are NOT bound by these standards. Filed during the pre-spike concept-mastery sweep for completeness, not because anything in MK3 hinges on it.

Core claim

Nautilus uses the Divio four-type documentation system (Tutorial, How-to, Explanation, Reference) and enforces strict MDX/markdown conventions through pre-commit hooks. Every page picks one type; mixing types on a single page is treated as a defect. The site is built with fumadocs (Next.js + MDX), so MDX components like <Tabs>, <Steps>, <Accordions>, <Files>, <Cards>, and <TypeTable> are available in any .md file without imports.

When it applies

You are filing a PR against nautechsystems/nautilus_trader that touches docs/**.
You are upstreaming an adapter (e.g., a hypothetical UW adapter) and need to ship a venue page under docs/integrations/.
You are writing a blog/post that will be consumed by the Nautilus community and want the conventions to match.

When it does NOT apply

Cortana brain pages in ~/brain/. These follow ~/brain/RESOLVER.md and ~/brain/schema.md (two-layer compiled-truth + timeline model), which is a different - and intentionally simpler - convention.
Internal Cortana plans, postmortems, and design docs in this repo. Those use whatever convention the SDLC docs require.
Codex handoff prompts, ticket bodies, or PR descriptions.

Page-type decision tree (Divio)

Type	Purpose	Section	Voice
Tutorial	Teach by walking through a task	`tutorials/`	”Do this, then this, then this.”
How-to	Solve a specific problem	`how_to/`	”Here is how to achieve X.”
Explanation	Clarify design and architecture	`concepts/`	”Why it works the way it does.”
Reference	Describe the machinery	`api_reference/`	”Classes, fields, enums, options.”

Special cases:

getting_started/ mixes tutorial + setup (intentional onboarding path).
integrations/ mixes reference + how-to per venue (each venue page is self-contained).

Choosing rules:

Walks a newcomer through a learning experience → Tutorial.
Answers “How do I..?” for someone who already knows the system → How-to.
Explains why something works the way it does → Explanation.
Lists classes, config fields, enums, capabilities → Reference.

When one type would naturally pull from another, link instead of inline. A how-to that configures TradingNodeConfig links to the API reference; it does not redefine the fields.

Markdown conventions

Headings

# Level 1 (page title): title case.
## Level 2 and below: sentence case (capitalize first word + proper nouns only).
Always capitalize proper nouns (product names, technologies, acronyms).
Don’t skip levels.

This matches Google, Microsoft, and Anthropic doc conventions - chosen for international-reader and screen-reader accessibility, not preference.

Lists

Hyphens (-) for bullets. Never * or +.
Numbered lists only when order is load-bearing.
Period-terminate items that are complete sentences.
Consistent indentation for nesting.

Tables

Symmetrical column widths sized to widest cell.
Vertically aligned | separators.
Sentence case in cells.
Period-terminate notes/descriptions.
✓ for supported, - (hyphen) for unsupported. Never ✗.
Italicize unsupported emphasis: *Not supported*.
Empty cells stay empty when no content is needed.

Line length

Wrap at ~100–120 characters.
Break at natural points (after commas, conjunctions, phrases).
Avoid orphan words on new lines.
Code blocks and URLs may exceed the limit when needed.

Language and tone

Active voice (“Configure the adapter,” not “The adapter should be configured”).
Present tense for current behavior; future tense only for planned features.
Define jargon on first use.
Drop filler: “basically,” “simply,” “just” are banned.
Parallel structure inside lists.

Code references

Backticks for inline code, methods, classes, config keys.
Code blocks for multi-line examples (with imports + realistic values).
Reference code locations as file_path::function_name or file_path::ClassName - never line numbers (they go stale).

Admonition catalog

Admonition	Purpose
`:::note`	Supplementary context that clarifies but isn’t essential.
`:::info`	Important information the reader should be aware of.
`:::tip`	Helpful suggestions or best practices.
`:::warning`	Potential pitfalls or important caveats.
`:::danger`	Critical issues that could cause data loss or system failure.

Use sparingly - overused admonitions stop signaling.

MDX components (fumadocs)

All components are available in any .md file with no imports needed.

<Tabs> + <Tab> - language/variant code switchers (Python vs Rust).
<Steps> + <Step> - sequential procedures (numbered visually).
<Accordions> + <Accordion title="..."> - collapsible content.
<Files> / <Folder> / <File> - directory tree visualizations.
<Cards> + <Card title="..." href="..." /> - linked content grids (used heavily on landing pages).
<TypeTable> - parameter / type documentation tables.

These are the visual primitives for any contributed page; matching their shape is what makes a contribution feel native.

Building docs locally

The docs.md style page itself doesn’t spell out the local build command, but the Nautilus repo ships a Makefile with documentation targets. The typical workflow contributors use:

Edit .md files under docs/.
Run the docs preview target from the repo root (check Makefile for the current name; historically make docs or make docs-serve).
fumadocs serves the site at a localhost URL with hot reload.
Verify rendering of any MDX components touched.
Run pre-commit hooks (pre-commit run --all-files) - these enforce copyright headers, line endings, and other repo-wide conventions before the doc PR will pass CI.

For PR submission flow itself, see nautilus-developer-guide.md, which covers the three-branch model (develop / nightly / master), version numbers, and PR conventions.

Contributing pattern

A documentation PR against Nautilus should:

Pick exactly one type (Tutorial / How-to / Explanation / Reference) for any new page. If it doesn’t fit, the page is split.
Match the section’s existing conventions before introducing new structure. Existing pages are precedent.
Use MDX components for tabs, steps, file trees, cards - not custom HTML or ad-hoc formatting.
Link, don’t inline. Cross-reference other pages instead of repeating their content.
Pass pre-commit + CI. Hooks enforce most conventions; CI rebuilds the docs site to catch broken links and bad MDX.

For an adapter contribution (the only realistic Cortana path back), the adapter ships:

An entry under docs/integrations/<venue>.md (mixed reference + how-to, per the section convention).
Updates to any cross-cutting concept pages that need to mention the new venue.
API reference auto-generated from docstrings - keep numpy-style docstrings on every public class/method.

Cortana MK3 implications

Minimal. Cortana MK3 is a consumer of Nautilus, not a contributor - at least at the MVP timeline. The brain pages we file under ~/brain/ are for our own retrieval and follow ~/brain/RESOLVER.md, which is a different and intentionally lighter convention (two-layer compiled-truth + timeline, slug-based identity, no Divio typing).

This page only becomes load-bearing if:

We decide to upstream the UW adapter (mentioned as a “would-be useful contribution” in nautilus-developer-guide.md’s adapter section). At that point we’d ship docs/integrations/unusual_whales.md and need to match section conventions.
We contribute documentation fixes back as a goodwill gesture during MK3 migration. Same conventions apply.
We adopt fumadocs / MDX for the Cortana customer-facing docs site (Customer #1 is Cody; the docs site is post-MVP). In that case we’d inherit the component catalog above.

Until any of those happen, this page is reference-only. The active constraint on Cortana documentation is ~/brain/RESOLVER.md and ~/brain/schema.md, not Nautilus’s docs style.

Timeline

2026-05-07 | Cody - Filed during pre-spike concept mastery sweep batch 7 (developer guide).

CortanaROI Brain

Explorer

nautilus-dev-docs