Authoring and styling guidelines for the Opentrons /docs MkDocs project. Covers file conventions, frontmatter, page titles, header IDs, image formats, tables, code blocks, Python API reference (mkdocstrings, autorefs, macros), and CSS patterns (parts lists, screenshots, icons, instruction lists, side-by-side figures, fonts, colors). Use when writing, editing, or reviewing any file in the docs/ directory, or when the user asks about MkDocs conventions, docstrings, CSS classes, or the Python API reference.
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.
/docsThe /docs directory is organized to support multiple documentation publications, site-global shared resources, and project build scripts.
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 |
mkdocs-monorepo-plugin./docs/mkdocs.yml aggregates all publications for the overall site, referencing their content via the monorepo plugin.docs/shared/: Shared Content and Resourcesdocs/shared/ holds assets, MDX-style includes, and support content used across multiple publications:
docs/shared/images/ — interface elements used in multiple publications.docs/shared/icons/ — custom Opentrons SVG icons.docs/shared/partials/ — HTML files used to modify the base Material theme.docs/shared/ (e.g., opentrons-theme.css, instruction-manuals.css).shared/ are navigation pages, like docs/shared/modules/index.md./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.pyproject.toml specifies the uv setup, including the mkdocs package and required plugins.Makefile: Contains commands for building the docs using the virtual environment.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.
opentrons-app.mdmkdocs.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.---