Docs

Opentrons Docs: MkDocs Authoring Guide

The /docs project uses MkDocs with the Material theme, the monorepo plugin, mkdocstrings (Python), autorefs, and macros. Config lives in docs/mkdocs.yml. Extra CSS: opentrons-theme.css, instruction-manuals.css, python-api.css.

Directory Structure of /docs

The /docs directory is organized to support multiple documentation publications, site-global shared resources, and project build scripts.

Publication Directories (Multiple MkDocs Projects)

• Each major documentation set ("publication") exists in its own subdirectory, with its own mkdocs.yml and content:

  Publication Directory	Description
  docs/absorbance-plate-reader/	Absorbance Plate Reader Module manual
  docs/flex/	Opentrons Flex robot manual
  docs/heater-shaker/	Heater-Shaker Module manual
  docs/hepa-uv/	HEPA/UV Module manual
  docs/protocol-designer/	Protocol Designer application manual
  docs/python-api/	Python API reference and guides
  docs/stacker/	Flex Stacker Module manual
  docs/temperature-module/	Temperature Module manual
  docs/thermocycler/	Thermocycler Module manual

• Each publication is a self-contained MkDocs project, but shares a unified build/serve flow via the monorepo and the mkdocs-monorepo-plugin.
• New publications may be added for new (or newly documented) software or hardware products.
• Top-level /docs/mkdocs.yml aggregates all publications for the overall site, referencing their content via the monorepo plugin.

docs/shared/: Shared Content and Resources

• docs/shared/ holds assets, MDX-style includes, and support content used across multiple publications:
  • Images: docs/shared/images/ — interface elements used in multiple publications.
  • Icons: docs/shared/icons/ — custom Opentrons SVG icons.
  • Theme overrides: docs/shared/partials/ — HTML files used to modify the base Material theme.
  • CSS: Sitewide overrides in docs/shared/ (e.g., opentrons-theme.css, instruction-manuals.css).
• Refer to these resources in any publication via the monorepo plugin's path mapping.
• The only user-facing pages in shared/ are navigation pages, like docs/shared/modules/index.md.

3. Scripts and Ancillary Files

• Top-level /docs/ contains scripts and files for building, developing, and managing the documentation site:
  • mkdocs.yml — main config aggregating all sub-projects with the monorepo plugin.
  • Python setup: pyproject.toml specifies the uv setup, including the mkdocs package and required plugins.
  • Makefile: Contains commands for building the docs using the virtual environment.
• These files support the docs build but are not included as user-facing content.

Recommendation: Add your new publication as a subdirectory under /docs/, and place shared assets only in shared/. Scripts and configuration should remain at the top level unless specific to a publication.

File Conventions

• Filenames: Short, lowercase, hyphen-separated. Example: opentrons-app.md
• No H1 in markdown files. The page title comes from mkdocs.yml nav.
• title frontmatter: Required on every page. Controls the sticky title when scrolling and search results. Format: "Publication Name: Page Title". Omit repeated words.

---
title: "Opentrons Flex: Support and Contact Information"
---

• Hide TOC (cover pages only):

---
title: "HEPA/UV Module Instruction Manual"
hide: TOC
---

Header IDs

The autorefs plugin warns on duplicate headings across the entire site. Add unique IDs to disambiguate:

## Tips and tip racks { #tips-and-tip-racks-ot2 }
## Tips and tip racks { #tips-and-tip-racks-flex }
## Air gap { #air-gap-building-block }
## Air gap { #air-gap-complex }

Format: slug of header text + hyphen + short unique suffix. The # and spaces inside { } are required.

Images

• Vector illustrations: SVG preferred.
• Raster (screenshots, renders): PNG. High-DPI (2×) for screenshots. Resample large files to ≤1200px wide. Optimize with ImageOptim before committing.

Tables

Use Markdown tables by default:

| Specification | Description |
|:--------------|:------------|
| Module weight | 790 g       |

Switch to HTML tables when you need: rowspan/colspan, embedded lists, or CSS class attributes (e.g., .my-dot status icons).

Column widths (use sparingly — only when auto-widths are unusable):

| Setting {style="width: 25%;"} | Description |
|------|------|
| Flow rates | Set aspirate/dispense speed. |

Requires attr_list in markdown_extensions (already enabled globally).

Code Blocks

Always declare the language explicitly for syntax highlighting:

```python
foo = "bar"
```

Python API Docs (PAPI)

Version Notices

No special plugin — use italic text in its own paragraph:

*New in version 2.15*

*Changed in version 2.16:* The `mount` parameter is optional.