mkdocs-specdeck-plugin

A MkDocs plugin that reads specdeck build output and generates a documentation site mirroring the component specification structure.

How it works

The plugin reads YAML files from a dist/ directory (produced by specdeck build) and generates MkDocs pages from them. The directory hierarchy in dist/ becomes the site navigation automatically.

Each YAML file is rendered as a page with:

• Title and description at the top
• Specs as a table: Key | Value | Description
• Events and actions sections when present

Installation

pip install mkdocs-specdeck-plugin

Or in development:

pip install -e .

Usage

Add to mkdocs.yml:

plugins:
  - specdeck:
      dist_dir: dist   # default; path relative to mkdocs.yml

Then run:

mkdocs serve   # local preview
mkdocs build   # production build

dist/ YAML schema

title: Note Input
description: Optional description
specs:
  formLabelText: Notes
  formInputPlaceholderText: Write your note here...
  # verbose form:
  someKey:
    value: some text
    description: explains the spec

CI / deployment

The specdeck pipeline has two decoupled steps:

1. specdeck build runs on merge/tag → writes dist/ → committed or uploaded as artifact
2. MkDocs build reads dist/ → deploys site

The plugin only reads from dist/ and has no dependency on specdeck internals.

Requirements

• Python 3.8+
• MkDocs 1.4+
• PyYAML 6.0+