Documentation Style Guide¶

A practical writing guide for contributors creating or updating pages in this documentation site.

Purpose¶

Use this page as the default style reference for:

• page structure and headings
• callouts and notes
• tables and code examples
• image formatting
• theme colors and icon usage

Quick checklist¶

Before opening a pull request, verify:

• Page appears in mkdocs.yml nav.
• No [TOC] marker is present.
• Admonitions use !!! syntax.
• Config examples use ini code fences.
• New screenshots are readable and centered where needed.
• Page ends with a single --- line.

Headings and section flow¶

Use sentence-case headings and keep section structure shallow where possible.

Example structure:

# Feature Name

## Concept

## Hardware setup

## Parameter setup

## Commands

## Troubleshooting

## See also

---

Admonitions (callouts)¶

Use Python-Markdown admonitions:

!!! note "Title"
    Body text.

Recommended types:

Use ??? instead of !!! for collapsible admonition content.

Rendered examples:

Tabbed admonition content using ===

Tables¶

Use simple pipe tables with short headers. Keep units in headers or in a Notes column.

Template:

| Parameter | Default | Typical range | Notes |
| --- | --- | --- | --- |
| `parameter_name` | `1.0` | `0.8-1.2` | What changing it does |

Example:

Code blocks and commands¶

Use fenced code blocks with explicit language.

• Use ```ini for config examples (including cfg-like snippets).

  # mmu_parameters.cfg
  toolhead_post_load_tighten: 60
  extruder_homing_max: 50
  

• Use ```bash for commands genuinely entered in a Linux shell, such as cd, git, make, or installer commands.

  make docs
  cd ~/Happy-Hare && ./install.sh -z -t -i
  

• Use ```{.text .console-command} for console input to the printer. To join a command and its output visually, put its console-output fence immediately afterward.

• Use ```{.text .console-output} for output returned by the printer.

  MMU_SLICER_TOOL_MAP PURGE_MAP=1
  

  -------- Slicer MMU Tool Summary ---------
  2 color print (Purge volume map loaded)
  T0 (Gate 0, ABS, ff0000, 240°C)
  

  - Use ```text for unclassified plain text.

  Regular preformatted text
  

Images and screenshots¶

For menuconfig or UI screenshots in narrative pages, center images and set width to improve readability in long pages.

<p align="center">
  <img src="Feature-Example/screen-01.png" alt="Feature setup screen" width="70%">
</p>

Guidance:

• Prefer one screenshot per concept step.
• Keep alt text descriptive and task-oriented.
• Avoid low-contrast crops or tiny text.

Theme and color guidance¶

Site theme direction (from mkdocs.yml):

• Primary: black
• Accent: pink
• Light scheme: default
• Dark scheme: slate

Use semantic styling rather than hard-coded inline colors whenever possible.

The site also applies a tri-color marker before H2 headings via CSS in doc/assets/stylesheets/extra.css.

Icons and icon repositories¶

This site uses Material-style icon identifiers in config (examples: material/tablet-dashboard, fontawesome/brands/github).

Useful icon references:

Lucide
Material Design
FontAwesome
Octicons
Simple Icons

Example social icon entries:

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/moggieuk/Happy-Hare
      name: Happy Hare on GitHub
    - icon: material/tablet-dashboard
      link: https://github.com/moggieuk/KlipperScreen-Happy-Hare-Edition
      name: KlipperScreen Happy Hare Edition on GitHub

Common mistakes to avoid¶

• Adding [TOC] to pages.
• Using GitHub callout syntax like [!NOTE].
• Using unsupported admonition names such as important.
• Adding Mermaid fenced blocks where deterministic rendering is required.
• Leaving a page out of nav after creating it.

Suggested workflow for knowledge workers¶

1. Draft page sections first.
2. Add callouts and tables second.
3. Add screenshots and links third.
4. Run local preview.
5. Confirm nav placement and section anchors.