zoduki

MkDocs plugin that turns assembly guides into step-by-step pages. Works with Material for MkDocs with no theme overrides required.

Each step shows one action at a time: images and thumbnails on the left, instructions on the right, with Previous/Next navigation pinned to the bottom of the viewport.

Install

In your MkDocs project:

uv add mkdocs-zoduki mkdocs-material

Add to mkdocs.yml:

plugins:
  - search
  - zoduki:
      enabled_by_default: true
      step_heading_level: 3

Run the site:

uv run mkdocs serve

Writing a guide

Structure your Markdown like this:

• The page title (# or Setext) is the guide name shown in the breadcrumb bar.
• ## headings group steps into subsections in the left nav.
• ### headings each become one step. Everything under a ### (bullets, images, text) stays in that step.

# X Gantry Assembly

## Prepare back plate

### Install fasteners

* Insert 4x `m5-hex-lock-nut` into the pockets shown.

    ![Nut pockets](images/nuts.webp)

* Add a drop of `blue-loctite` to each pocket.

### Inspect alignment

* Verify the plate sits flush against the datum surface.

Images

Put images under the bullet they illustrate (indented under the list item). Images are moved to the left-side gallery for that step. The Next button cycles through all images in the current step before advancing to the next step.

Bullet colors

Bullets that contain an image get a colored box and matching image border automatically. Override with an inline note:

* Install the bracket {color=blue}

    ![Bracket](images/bracket.webp)

* Text-only note with no image gets a neutral box.

* Disable coloring explicitly {color=none}

Named colors: blue, green, orange, purple, red, teal, yellow, pink. Hex values like #3b82f6 also work.

Per-page control

Disable zoduki on a specific page with front matter:

---
zoduki: false
---

Or leave enabled_by_default: false in the plugin config and opt in per page:

---
zoduki: true
---

Options

Option	Default	Description
enabled_by_default	false	Apply zoduki to every page unless overridden
page_meta_key	zoduki	Front matter key for per-page enable/disable
step_heading_level	3	Heading level that starts a new step (###)
min_steps	2	Minimum steps required before transforming a page

Deep links

Each step gets a stable URL hash from its heading, e.g. #install-fasteners. The left nav links directly to steps and stays in sync with Previous/Next navigation.

List view

A "List view" toggle switch appears at the top of every zoduki page, next to the progress indicator. It flips the page from one-step-at-a-time into a single scrollable document with every step stacked in order — useful for skimming a whole guide, printing it, or using the browser's find-in-page (Ctrl/Cmd+F) to search across every step at once, none of which work while steps are hidden one at a time.

The choice is remembered per-browser (via localStorage) and applies across the whole site, not just the current page, so a reader who prefers the flat view keeps it as they navigate between guides.

---

Development

Clone the repo and install everything with uv:

git clone https://github.com/sphawes/zoduki.git
cd zoduki
uv sync