Documentation style guide¶

What every HardFOC documentation site contains, how its pages are written and what a README looks like. The pilot site, hardfoc/hf-tmc9660-driver, follows every rule here; copy its structure.

Voice¶

Plain and specific. "SPI mode 3, up to 10 MHz", not "supports high-speed SPI". Numbers, names, units.
Second person, present tense, active voice. "Call init() before anything else", not "The init function should be called".
Short sentences. One idea each. A paragraph is three to five sentences.
No hype, no filler. No "simply", "just", "easily", "powerful", "comprehensive", "seamless", "robust".
No emoji in headings, lists or tables. No walls of bold. No exclamation marks.
Sentence case for titles and headings: "Bus settings", not "Bus Settings".
British or American spelling: either, consistently within a repository.
True statements only. Every API name, signature, pin, register and number is checked against the headers or the datasheet. When something is derived rather than measured, say so.
Never mention how the page was produced. No "generated by", no tool or assistant names.

Every page¶

A title (# Title, level one, exactly one), matching its navigation entry.
A purpose line right under it: one sentence saying what the reader gets from the page. The theme renders it as the lead paragraph.
Sections (##) in the order a reader needs them. A section that is only a link list belongs in a table or in the navigation instead.
A next step when there is an obvious one (Next: [Porting](porting.md)).

No Jekyll front matter, no Liquid. Material front matter is allowed only for hide: (the home page hides the navigation and table of contents).

Components¶

The theme styles these; use them instead of inventing markup.

Need	Write	Notes
A warning that prevents damage or lost hours	`!!! warning "Title"` / `!!! danger`	At most two per page. `note`, `tip`, `example` for the rest
Optional detail	`??? note "Title"`	Collapsed by default
Alternatives (SPI / UART, ESP-IDF / CMake)	`=== "SPI"` tabs	Same structure in each tab
Code	fenced block with a language; `title="file.cpp"` for a file	Code from a compiled file: `--8<-- "tests/docs/x.cpp:section"`
Registers, parameters, pins, options	a table	Header row, units in the header, code font for names
Bit fields	a table inside `<div class="hf-registers" markdown>`	Offset and name columns get code font
Sequence or state machine	a `mermaid` fence	Themed for light and dark automatically
Architecture, signal flow, layouts	a figkit figure	Light and dark from one layout, checked for contrast
A light-only image (vendor SVG, photo)	`![alt](x.svg){ .hf-plate }`	Sits on a white plate in dark mode
Steps	`<div class="hf-steps" markdown>` around an ordered list	Numbered circles and a rail
The chip or board summary	the chip card (below)	Home page of a driver or HAL
A short label	`<span class="hf-badge">SPI</span>`	Tones: `hf-badge--teal`, `--amber`, `--rose`
A link into Doxygen	`[`Class::method`](api/....html){ .hf-api }`	From `api-reference.md`, or any page
Landing hero	`<div class="hf-hero" markdown>` with `hf-kicker`, `# Title`, a paragraph, buttons	Home page only
Navigation cards	`<div class="grid cards" markdown>`	Home page; four to six cards

Chip card¶

<div class="hf-chip" markdown>
<div class="hf-chip__head">
<span class="hf-chip__kicker">Smart gate driver with on-chip FOC</span>
<span class="hf-chip__name">TMC9660</span>
<span class="hf-chip__vendor">Analog Devices (Trinamic)</span>
</div>

Interface
:   SPI mode 3 up to 10 MHz, or UART

Supply
:   7.7 V to 70 V

[Datasheet](datasheet/tmc9660.pdf) · [Reference manual](datasheet/ref.pdf)
</div>

Five to seven rows: function, interface (mode, speed, address), supply, key limits, package, and the mode the driver uses. A board uses class="hf-chip hf-chip--board" with MCU, power input, connectors, chips on board.

Code¶

It compiles against the real API. In a C++ repository, every snippet longer than one line lives in build (an OBJECT library, warnings on) and is included in the page with --8<-- "tests/docs/x.cpp:name". Instantiate the driver template over the documented port so the whole API is compiled.
It is the smallest complete thing. Includes, the object, the calls, the error check. No // ... in a block that claims to be complete.
It checks results. Every driver call returns a status: show what to do with it.
Names are real. A reader can paste them. One-line inline names (setTargetVelocityRpm()) are checked by searching the headers.
The README quickstart is a generated region () copied from the same compiled file, so it cannot drift.

Figures¶

figkit for architecture and anything drawn from the code: one module per figure in docs/diagrams/figures/<id>.py, data() reads the facts from the headers, build() lays out cards. The build refuses text under 4.5:1 contrast in either theme, overlaps and missing alt text; hardfoc-docs figures --check fails CI when the code changed and the figure did not. Embed with  / .
Mermaid for sequences and state machines.
Vendor diagrams only as SVG or compressed PNG, with { .hf-plate }, never screenshots of PDFs.
Alt text on every image: one sentence that says what the figure shows, not "diagram". The build fails on a missing alt.
PDFs (datasheets, manuals) live in docs/datasheet/ and are linked, never embedded; the site links them on GitHub, which renders them.

Tables¶

Use a table whenever there are three or more items with the same attributes: pins, registers, parameters, options, commands, error codes, compile-time switches. Put units in the header (Range (V)), names in code font, and keep cells short; long prose goes under the table.

Links¶

Link pages by file ([Porting](porting.md#threads)); MkDocs checks them in strict mode.
Link repository files relatively ([`inc/x.hpp`](../inc/x.hpp)); the plugin turns them into GitHub links at the commit that was built.
Link the API reference with api/...html; the link check verifies it after Doxygen is merged.
External links go to the primary source (vendor page, datasheet, specification).

Standard page sets¶

Driver (`hf-*-driver`)¶

Page	File	Contains
Home	`index.md`	Hero (what, one-sentence why, buttons), the "no platform code" paragraph, chip card, "What you get" (5-7 bullets, each linking its page), navigation cards
Quickstart	`quickstart.md`	Safety note if it moves hardware; wiring table; add the driver; the port (compiled); a ~15-line example (compiled); what each step does; a "if it does not work" table
Installation	`installation.md`	Requirements; submodule; CMake target and options; ESP-IDF component; build layout; version; compile-time switches
Hardware	`hardware.md`	Pin table(s) with directions; control pins; bus settings table (mode, speed, frame, timing); a timing diagram or Mermaid sequence for the protocol; power ranges; errata that affect the host; evaluation boards; reference documents table
Architecture	`architecture.md`	The layer figure (core, communication interface, platform port); a table of layers with files; one call traced through the layers (Mermaid); design choices (CRTP, no heap); source map
API guide	`api-guide.md`	Task-oriented, compiled snippets: the shape of the API (subsystems table); initialise; configure; read; write; batch or stream if any; raw register / parameter access; errors and faults (a table of signals); tuning
API reference	`api-reference.md`	Button to `api/index.html`; a "start here" table of the five most useful Doxygen pages
Examples	`examples.md`	`<!-- generated: examples -->` (from `examples/*/app_config.yml`); one-time setup; "what to read in an example" table
Porting	`porting.md`	The interface methods table with contracts; the port for each bus (compiled); rules for the transfer; control-pin levels; reference implementation; how to check a port; threads
Testing and CI	`testing.md`	Host tests (how to run, what each file covers); compiled snippets; CI workflows table; hardware tests
Troubleshooting	`troubleshooting.md`	Symptom, cause, fix; start with the cheapest check
Changelog	`changelog.md`	`# Changelog`, a purpose line and `--8<-- "CHANGELOG.md:N"` (from the line after the file's own title)
Figures	`diagrams/index.md`	Generated by `hardfoc-docs figures`

Deep-dive pages (bootloader, protocols, timing, units, calibration) go under Concepts; configuration references under Guides. Navigation (docs/.nav.yml) is always five tabs:

nav:
  - Home: index.md
  - Get started: [Quickstart, Installation, Hardware]
  - Concepts: [Architecture, deep dives ...]
  - Guides: [API guide, Configuration, Porting, Examples, Troubleshooting]
  - Reference: [API reference, Testing and CI, Figures, Changelog]

Core library (`hf-core`, `hf-utils-`, `hf-*-interface-wrap`, `hf-pincfg`)¶

Home (hero, what problem it solves, a feature list, a "used by" table), Quickstart (smallest use), Concepts (the model the library implements, with a figure), API guide (by task), API reference, Integration (CMake / ESP-IDF, configuration macros), Testing and CI, Changelog. A utilities collection gets one page per utility under Guides, each with purpose, a compiled example and complexity or memory notes.

HAL (`hf-hal-*`)¶

Home with a board card (hf-chip hf-chip--board): MCU, power, connectors, chips on board; Quickstart (flash an example, see output); Hardware (block diagram figure, pin map as a generated table from the pin configuration, connectors, power tree); Architecture (managers, how drivers are wired, figure); one guide page per board function; API reference; Examples; Bring-up and troubleshooting; Changelog.

Product (`hf-*` firmware products)¶

Home (what the product does, a photo or render with alt text, status), Getting started (flash, connect, first run), Architecture (tasks, data flow, figures), Operation (modes, commands, configuration), Hardware (link the HAL site), Development (build, test, release), Troubleshooting, Changelog. Decisions as ADRs under Reference.

CI and tool repositories (`hf-general-ci-tools`, `hf-espidf-ci-tools`, `hf-espidf-project-tools`)¶

Home (what it provides, a table of workflows or scripts), Quickstart (the smallest caller), one page per workflow or script (purpose, jobs and permissions, inputs table generated from the YAML, example caller, failure modes), Versioning, Migration guides, Changelog.

Organisation (`.github`, `hardfoc.github.io`)¶

The portal (hardfoc.github.io) is the org home: what HardFOC is, a card per product and HAL, a table of every driver with its chip, bus and docs link, and contribution links. .github holds the profile README following the README standard, plus community files.

README standard¶

The README is the front door on GitHub. It is short and points to the site.

# Name and a hero line: one sentence, what it is and what it does.
Badges that are true, in this order, only those that exist: CI (the main test workflow, branch=main), docs (the docs workflow, linking the site), license, latest release (only once a release exists). No coverage badge without coverage, no "PRs welcome", no badge for a language version.
The documentation link in bold.
One diagram: the layer or block figure (figkit marker).
A 30-second example: the generated quickstart region.
What it does: five to seven bullets.
Install: the submodule line and the CMake lines.
Documentation: a table of the five or six most useful pages, linked to the site (/latest/...).
Tests: one command line.
License: one line.

No table of contents, no walls of emoji, no feature lists with check marks, no badges that link nowhere, no duplicated API tables (that is the site's job).

Checks that enforce this¶

Check	Where	Fails on
`mkdocs build --strict`	PR CI	broken links and anchors, pages missing from the nav, no H1, Jekyll front matter, Liquid, a page colliding with `api/`, an image without alt text or file
`hardfoc-docs check`	PR CI	a figure or generated region that no longer matches the code
Host build of `tests/docs/`	PR CI (repository)	a snippet that does not compile
lychee offline	PR CI	a broken link or anchor in the built site, API included
Lighthouse	PR CI	performance, accessibility, best practices or SEO under budget
markdownlint	PR CI (repository)	Markdown style