mkdocs-process-timeline 0.2.0

MkDocs plugin that renders process timeline shortcode content from YAML.

mkdocs-process-timeline

mkdocs-process-timeline renders a process timeline from YAML with a Markdown shortcode.

It is an MkDocs plugin that:

• finds ::process-timeline{file="..."} in page Markdown
• loads a YAML file relative to docs_dir
• validates the YAML structure
• replaces the shortcode with rendered HTML
• automatically includes the bundled process-timeline.css and process-timeline.js assets

The rendered output contains:

• a summary header with counts
• a dark clickable timeline journey
• a sticky left-side page progress bar inside the rendered timeline on desktop layouts
• anchor links to detailed milestone sections
• responsive milestone detail cards
• lightweight JavaScript for viewport progress tracking

Install

pip install mkdocs-process-timeline

For local development:

pip install -e ".[dev]"

MkDocs configuration

Enable the plugin in mkdocs.yml:

plugins:
  - search
  - mkdocs-process-timeline

No extra CSS or JavaScript setup is required. The plugin injects its bundled stylesheet and progress script automatically.

Usage

Add the shortcode to a page:

::process-timeline{file="processes/delivery.yml"}

Whitespace around file= is also supported:

::process-timeline{ file = "processes/delivery.yml" }

The YAML file path is resolved relative to docs_dir, not relative to the current Markdown file.

Example:

• if docs_dir is docs
• and the shortcode is ::process-timeline{file="processes/delivery.yml"}

then the plugin reads:

• docs/processes/delivery.yml

Progress bar

The timeline can render a sticky progress bar beside the milestone details on desktop layouts. It shows page scroll progress: empty at the top of the page and full at the bottom.

Progress is enabled by default. To make the setting explicit, add this top-level YAML field:

show_progress: true

To hide the progress bar for a specific timeline:

show_progress: false

When the progress bar is disabled, the milestone detail sections use the full available content width.

Minimal example

Markdown page:

# Delivery Process

::process-timeline{file="processes/delivery.yml"}

YAML file:

title: Delivery Process
description: A simple example showing how to define a delivery workflow in YAML.
show_progress: true
milestones:
  - id: intake
    title: Intake
    summary: Capture the incoming request and verify completeness.
    description: Review the request, collect missing inputs, and log the work item.
    duration_weeks: 1
    contact:
      name: Jordan Smith
      role: Intake Coordinator
      email: [e-mail]
      support:
        label: Open intake support request
        url: https://example.com/support/intake
    references:
      - label: Intake checklist
        url: https://example.com/intake-checklist
    tasks:
      - title: Register request
        description: Create the delivery request record in the intake workflow.
        url: https://example.com/docs/register-request
      - title: Confirm mandatory inputs
        description: Verify the requester attached the required initial materials.
        url: https://example.com/docs/confirm-inputs
  - id: planning
    title: Planning
    summary: Convert the request into a structured delivery plan.
    description: Agree scope, owners, and target dates before execution begins.
    duration_weeks: 2
    contact:
      name: Casey Taylor
    tasks:
      - title: Define milestones
        description: Break the delivery into measurable execution checkpoints.

YAML schema

Top-level fields:

• title: string
• description: string
• show_progress: optional boolean, defaults to true
• milestones: non-empty list

Milestone fields:

• id: string, unique
• title: string
• summary: string
• description: string
• duration_weeks: positive int or float
• contact:
  • name: string
  • role: optional string
  • email: optional string
  • support: optional
    • label: string
    • url: string
• references: optional
  • label: string
  • url: string
• tasks: list of objects
  • title: string
  • description: string
  • url: optional string

Validation rules

The plugin validates input before rendering.

Top-level validation:

• the YAML file must exist
• the YAML root must be a mapping
• milestones must be a non-empty list
• when present, show_progress must be a boolean

Milestone validation:

• milestone ids must be unique
• id, title, summary, description are required non-empty strings
• duration_weeks must be a positive number
• contact must be a mapping
• contact.name is required
• when present, contact.role must be a non-empty string
• when present, contact.email must be a string
• when present, contact.support must be a mapping with label and url
• when present, references must be a list of mappings with label and url
• tasks must be a list of mappings
• each task must contain title and description
• when present, task.url must be a non-empty string

Validation errors include the filename and milestone id where possible.

Rendered structure

For each rendered timeline:

• timeline cards link to #milestone-{id}
• detailed milestone sections use matching id="milestone-{id}"
• a sticky left-side page progress bar appears inside the rendered timeline on desktop unless show_progress: false
• summary stats include:
  • milestones
  • estimated duration
  • required tasks
  • references
• task titles render as links only when task.url is present
• support renders only when contact.support is present
• references panel renders only when references exist

Development

Install the project in editable mode:

python3 -m pip install -e ".[dev]"

Run tests:

pytest

Build the example site:

mkdocs build -f examples/basic/mkdocs.yml

Build distributable artifacts:

python3 -m build

Check the generated distributions before publishing:

python3 -m twine check dist/*

Serve the example locally:

mkdocs serve -f examples/basic/mkdocs.yml

Then open:

• http://127.0.0.1:8000/

Example

See examples/basic for a working sample project:

• examples/basic/mkdocs.yml
• examples/basic/docs/index.md
• examples/basic/docs/processes/delivery.yml

Publishing

Typical release flow:

python3 -m pip install -e ".[dev]"
pytest
mkdocs build -f examples/basic/mkdocs.yml
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload dist/*