Gantt
The Gantt extension provides a beautiful implementation of Gantt diagrams for MkDocs. A Gantt diagram is great to provide detailed information of chronological events, like a project roadmap.
Definition Phase
Creation Phase
Feedback Phase
Delivery Phase
How to use¶
Edit your mkdocs.yml file to include the extra CSS file from Neoteroi
mkdocs-plugins and the neoteroi.projects extension:
extra_css:
- css/neoteroi-mkdocs.css
...
markdown_extensions:
- neoteroi.projects
...
Input object¶
Examples¶
::gantt::
[
{
"title": "Definition Phase",
"activities": [
{
"title": "Creative Brief",
"start": "2022-03-03",
"lasts": "1 day"
},
{
"title": "Graphic Design Research",
"start": "2022-03-02",
"lasts": "2 weeks"
},
{
"title": "Brainstorming / Mood Boarding",
"start": "2022-03-11",
"lasts": "2 weeks"
}
]
},
{
"title": "Creation Phase",
"activities": [
{
"title": "Sketching",
"start": "2022-03-21",
"lasts": "2 weeks"
},
{
"title": "Design Building",
"start": "2022-04-02",
"lasts": "4 weeks"
},
{
"title": "Refining",
"start": "2022-05-01",
"lasts": "2 weeks"
}
]
},
{
"title": "Feedback Phase",
"activities": [
{
"title": "Presenting",
"start": "2022-05-01",
"lasts": "3 days"
},
{
"title": "Revisions",
"start": "2022-05-02",
"end": "2022-05-31"
}
]
},
{
"title": "Delivery Phase",
"activities": [
{
"title": "Final delivery",
"start": "2022-06-05",
"end": "2022-06-06"
}
]
}
]
::/gantt::
::gantt::
- title: Definition Phase
activities:
- title: Creative Brief
start: 2022-03-03
lasts: 1 day
- title: Graphic Design Research
start: 2022-03-02
end: 2022-03-10
lasts: 2 weeks
- title: Brainstorming / Mood Boarding
start: 2022-03-11
end: 2022-03-20
- title: Creation Phase
activities:
- title: Sketching
start: 2022-03-21
end: 2022-04-01
- title: Design Building
start: 2022-04-02
end: 2022-04-20
- title: Refining
start: 2022-04-21
end: 2022-04-30
- title: Feedback Phase
activities:
- title: Presenting
start: 2022-04-22
end: 2022-05-01
- title: Revisions
start: 2022-05-02
end: 2022-05-10
- title: Delivery Phase
activities:
- title: Final delivery
start: 2022-05-11
end: 2022-05-12
::/gantt::
[gantt(./settings.yaml)]
[gantt(./settings.json)]
[gantt(https://www.neoteroi.dev/examples/gantt.yaml)]
[gantt(https://www.neoteroi.dev/examples/gantt.json)]
Schema¶
The input for a Gantt diagram is a list of activities having a shape described by the following scheme:
classDiagram
direction LR
class Event {
title: str
description: str | None = None
time: datetime | None = None
icon: str | None = None
}
class Activity {
title: str
start: date | None = None
end: date | None = None
lasts: str | None = None
description: str | None = None
events: Array of Event | None
activities: Array of Activity | None
}
Activity --> Event
Activity --> Activity
@dataclass(frozen=True)
class Event:
title: str
description: str | None = None
time: datetime | None = None
icon: str | None = None
@dataclass(frozen=True)
class Activity:
title: str
start: date | None = None
end: date | None = None
lasts: str | None = None
description: str | None = None
activities: List["Activity"] | None = None
events: List[Event] | None = None
Dates and times¶
The duration of activities can be described in two ways:
- specifying
startandendas dates or datetimes - specifying
startandlastsproperties
When using lasts, it is possible to use the following syntax:
| Days | Example | Alternative |
|---|---|---|
| lasts n days | lasts 10 days | days | day | d |
| lasts n weeks | lasts 2 weeks | weeks | week | w |
| lasts n months | lasts 3 months | months | month | m |
| lasts n years | lasts 3 years | years | year | y |
This feature is inspired by gantt diagrams in PlantUML.
Currently unsupported
- Time information is currently ignored, the extension only handles dates. Anyway, the input objects can still have detailed date and time information.
- The extension currently requires dates (year, month, day information): it cannot handle information having only number of days without month and year information (unlike PlantUML).
Using events¶
It is possible to define events for each activity in the plan. Events require a single date and are represented with circles.
Milestones
Definition Phase
Creation Phase
Feedback Phase
Examples:
::gantt::
[
{
"title": "Milestones",
"events": [
{
"title": "Kick-off meeting",
"time": "2022-03-03",
"icon": ":octicons-rocket-16:"
},
{
"title": "Final delivery",
"time": "2022-06-05",
"icon": ":octicons-sun-16:"
}
]
},
{
"title": "Definition Phase",
"activities": [
{
"title": "Graphic Design Research",
"start": "2022-03-02",
"lasts": "2 weeks"
},
{
"title": "Brainstorming / Mood Boarding",
"start": "2022-03-11",
"lasts": "2 weeks"
}
]
},
{
"title": "Creation Phase",
"activities": [
{
"title": "Sketching",
"start": "2022-03-21",
"lasts": "2 weeks"
},
{
"title": "Design Building",
"start": "2022-04-02",
"lasts": "4 weeks"
},
{
"title": "Refining",
"start": "2022-05-01",
"lasts": "2 weeks"
}
]
},
{
"title": "Feedback Phase",
"activities": [
{
"title": "Presenting",
"start": "2022-05-01",
"lasts": "3 days"
},
{
"title": "Revisions",
"start": "2022-05-02",
"end": "2022-05-31"
}
]
}
]
::/gantt::
::gantt::
- title: Milestones
events:
- title: Kick-off meeting
time: 2022-03-03
icon: ":octicons-rocket-16:"
- title: Final delivery
time: 2022-06-05
icon: ":octicons-sun-16:"
- title: Definition Phase
activities:
- title: Graphic Design Research
start: 2022-03-02
lasts: 2 weeks
- title: Brainstorming / Mood Boarding
start: 2022-03-11
lasts: 2 weeks
- title: Creation Phase
activities:
- title: Sketching
start: 2022-03-21
lasts: 2 weeks
- title: Design Building
start: 2022-04-02
lasts: 4 weeks
- title: Refining
start: 2022-05-01
lasts: 2 weeks
- title: Feedback Phase
activities:
- title: Presenting
start: 2022-05-01
lasts: 3 days
- title: Revisions
start: 2022-05-02
end: 2022-05-31
::/gantt::
Any activity can have events
The examples here show events in a single activity, but they can be added to any activity of a plan.
Subactivities¶
It is possible to define more than one item per row, using subactivities. Subactivities are always displayed inside the row of their root activity.
When defining activities, it is also possible to define the start date for the first item
in a tree of activities, and only specify how long following activities last. To add
breaks, add items having a skip property with a value describing a duration.
The following examples illustrate both features:
Developer
Tester
Technical writer
::gantt::
{
"start": "2022-03-01",
"activities": [
{
"title": "Developer",
"activities": [
{
"activities": [
{
"title": "Custom sign-up",
"lasts": "2 weeks"
},
{
"skip": "1 week"
},
{
"title": "Custom password reset",
"lasts": "2 weeks"
}
]
}
]
},
{
"title": "Tester",
"activities": [
{
"activities": [
{
"skip": "5 days"
},
{
"title": "Tests custom sign-up",
"lasts": "2 weeks"
},
{
"skip": "1 week"
},
{
"title": "Tests custom password reset",
"lasts": "2 weeks"
}
]
}
]
},
{
"title": "Technical writer",
"activities": [
{
"activities": [
{
"skip": "4 weeks"
},
{
"title": "Documents custom sign-up",
"lasts": "2 weeks"
},
{
"title": "Documents custom password reset",
"lasts": "2 weeks"
}
]
}
]
}
]
}
::/gantt::
::gantt::
start: 2022-03-01
activities:
- title: Developer
activities:
- activities:
- title: Custom sign-up
lasts: 2 weeks
- skip: 1 week
- title: Custom password reset
lasts: 2 weeks
- title: Tester
activities:
- activities:
- skip: 5 days
- title: Tests custom sign-up
lasts: 2 weeks
- skip: 1 week
- title: Tests custom password reset
lasts: 2 weeks
- title: Technical writer
activities:
- activities:
- skip: 4 weeks
- title: Documents custom sign-up
lasts: 2 weeks
- title: Documents custom password reset
lasts: 2 weeks
::/gantt::
Example
::gantt::
[
{
"title": "Example",
"start": "2022-01-01",
"activities": [
{
"title": "Feature 1",
"lasts": "10 day",
"activities": [
{
"skip": "10 days"
},
{
"title": "Activity 1.1",
"lasts": "30 days",
"activities": [
{
"skip": "5 days"
},
{
"title": "Activity 1.12",
"lasts": "30 days"
}
]
}
]
},
{
"title": "Activity 2",
"lasts": "10 days"
},
{
"title": "Activity 3",
"lasts": "20 days"
},
{
"title": "Activity 2",
"lasts": "10 weeks"
},
{
"title": "Activity 2",
"lasts": "10 weeks"
}
]
}
]
::/gantt::
::gantt::
- title: Beginning
start: 2022-01-01
activities:
- title: Feature 1
lasts: 10 day
activities:
- skip: 10 days
- title: Activity 1.1
lasts: 30 days
activities:
- skip: 5 days
- title: Activity 1.12
lasts: 30 days
- title: Activity 2
lasts: 10 week
- title: Activity 3
lasts: 20 days
- title: Activity 2
lasts: 10 week
- title: Activity 2
lasts: 10 week
- title: Beginning
start: 2022-01-01
activities:
- title: Activity 1
lasts: 10 day
activities:
- title: Activity 1.1
lasts: 30 days
- title: Activity 2
lasts: 40 week
- title: Activity 3
lasts: 20 days
::/gantt::
Options¶
| Name | Description | Default |
|---|---|---|
| id | Configures an id property on the root HTML element |
"" |
| month-width | Controls the size of the scale - represents the pixels width of a month with 30 days | 150 |
| month-format | Controls date formatting for months | "%B %Y" |
| no-groups | Disables groups (flag) | False |
| no-years | Disables years (flag) | False |
| no-weeks | Disables weeks (flag) | False |
| no-quarters | Disables quarters (flag) | False |
| no-days | Disables days (flag) | False |
| whole-years | Displays whole years from January to December (flag) | False |
| pastello | Applies a CSS class to use a color palette with milder saturation | False |
| vlines-pace | Controls how separator vertical lines are generated (each week or each month) | "monthly" or "weekly" |
Controlling the scale size¶
This extension produces diagrams displaying years, quarters, months, weeks, and days in
scale. To control the size of the scale, use the month-width option, which affects the
size of months having 30 days.
[gantt month-width=800(./docs/gantt/gantt-1.yaml)]
Definition Phase
Creation Phase
Feedback Phase
Delivery Phase
Displaying days
Days are not displayed when the default month size is used.
When month-width is sufficiently big, days are displayed automatically.
Gentler colors¶
It's possible to use a a different color palette with less saturated colors,
using the pastello flag.
[gantt pastello(./docs/gantt/gantt-1.yaml)]
Definition Phase
Creation Phase
Feedback Phase
Delivery Phase
Disabling groups¶
To disable groups on the left side, use the no-groups flag.
[gantt no-groups(./docs/gantt/gantt-1.yaml)]
Definition Phase
Creation Phase
Feedback Phase
Delivery Phase
Disabling parts of the periods¶
Use the no-years, no-weeks, no-quarters, or no-days to disable certain
periods displayed on the top. For example, to disable years and quarters:
[gantt no-years no-quarters(./docs/gantt/gantt-2.yaml)]
Milestones
Definition Phase
Creation Phase
Feedback Phase
Days default
Days are displayed by default, but only if their elements width would be at least of 20px.
Displaying full years¶
Gantt diagrams display by default the months between the smallest date and the biggest
date in the input data, from the beginning of the earliest month to the end of the latest
month. To display full years, from January to December, use the whole-years option.
[gantt whole-years(./docs/gantt/gantt-1.yaml)]
Definition Phase
Creation Phase
Feedback Phase
Delivery Phase
Icons support¶
The gantt extension integrates with Material for MkDocs icons, like shown in the examples above. The extension also supports links to images, like in the following example:
Parties
Last modified on: 2025-04-17 07:04:37