mkdocs-process-timeline 0.3.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 an explicit YAML file relative to docs_dir
• or, when no file is specified, loads a same-folder YAML file with the same name as the Markdown page
• 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

You can also omit the file path:

::process-timeline

or:

::process-timeline{}

In that form, the plugin looks beside the current Markdown page for a YAML file with the same base name. For example:

• docs/guides/delivery.md
• docs/guides/delivery.yaml or docs/guides/delivery.yml

If both .yaml and .yml files exist for the page, the build fails so the source is explicit.

You can also define the timeline inline by placing a YAML fence immediately after the shortcode:

::process-timeline
```yaml
title: Delivery Process
description: A timeline defined directly in Markdown.
milestones:
  - id: intake
    title: Intake
    summary: Capture the request.
    description: Gather the inputs needed to begin.
    duration_weeks: 1
    contact:
      name: Jordan Smith
    tasks:
      - title: Register request
        description: Create the delivery request record.
```

The empty-braces form also supports inline YAML:

::process-timeline{}
```yaml
title: Delivery Process
description: A timeline defined directly in Markdown.
milestones:
  - id: intake
    title: Intake
    summary: Capture the request.
    description: Gather the inputs needed to begin.
    duration_weeks: 1
    contact:
      name: Jordan Smith
    tasks:
      - title: Register request
        description: Create the delivery request record.
```

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.

Browser support

The bundled styles are scoped to the rendered timeline and are designed for current versions of Chrome, Edge, Firefox, and Safari on Windows, Linux, and macOS. The layout uses CSS Grid and supports responsive, print, reduced-motion, and Windows forced-colors/high-contrast modes.

The timeline also resets its own list spacing so MkDocs themes such as Material for MkDocs do not move timeline markers away from the vertical axis.

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:

rm -rf dist build *.egg-info
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/implicit.md
• examples/basic/docs/implicit.yaml
• examples/basic/docs/inline.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
rm -rf dist build *.egg-info
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload dist/*