Metadata-Version: 2.4
Name: mkdocs-process-timeline
Version: 0.1.1
Summary: MkDocs plugin that renders process timeline shortcode content from YAML.
License-Expression: MIT
Keywords: mkdocs,plugin,timeline,process,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: MkDocs
Classifier: Topic :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs>=1.6
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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` asset

The rendered output contains:

- a summary header with counts
- a dark clickable timeline journey
- anchor links to detailed milestone sections
- responsive milestone detail cards
- no JavaScript

## Install

```bash
pip install mkdocs-process-timeline
```

For local development:

```bash
pip install -e ".[dev]"
```

## MkDocs configuration

Enable the plugin in `mkdocs.yml`:

```yaml
plugins:
  - search
  - mkdocs-process-timeline
```

No extra CSS or JavaScript setup is required. The plugin injects its stylesheet automatically.

## Usage

Add the shortcode to a page:

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

Whitespace around `file=` is also supported:

```md
::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`

## Minimal example

Markdown page:

```md
# Delivery Process

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

YAML file:

```yaml
title: Delivery Process
description: A simple example showing how to define a delivery workflow in YAML.
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: jordan@example.com
      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
- `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

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}"`
- 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:

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

Run tests:

```bash
pytest
```

Build the example site:

```bash
mkdocs build -f examples/basic/mkdocs.yml
```

Build distributable artifacts:

```bash
python3 -m build
```

Check the generated distributions before publishing:

```bash
python3 -m twine check dist/*
```

Serve the example locally:

```bash
mkdocs serve -f examples/basic/mkdocs.yml
```

Then open:

- `http://127.0.0.1:8000/`

## Example

See [examples/basic](examples/basic) for a working sample project:

- [examples/basic/mkdocs.yml](examples/basic/mkdocs.yml)
- [examples/basic/docs/index.md](examples/basic/docs/index.md)
- [examples/basic/docs/processes/delivery.yml](examples/basic/docs/processes/delivery.yml)

## Publishing

Typical release flow:

```bash
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/*
```
