Metadata-Version: 2.4
Name: mkdocs-process-timeline
Version: 0.3.0
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 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

```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 bundled stylesheet and progress script 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`

You can also omit the file path:

```md
::process-timeline
```

or:

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

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

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

```yaml
show_progress: true
```

To hide the progress bar for a specific timeline:

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

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

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