
Somewhere in almost every doctorate there is a moment, usually late at night, where you are nudging a coloured rectangle three pixels to the left so that _Phase 2_ finally lines up with the right month. You are not doing research. You are doing graphic design, badly, in a tool that was never meant for it. I have made that slide more times than I would like to admit.

<Image src="/posts/why-i-built-gantt-charter/hero.png" width="1280" height="640" alt="A Gantt Charter timeline with task bars, phase colours, and milestone diamonds.">
  Gantt Charter: task bars, phase colours, and milestone indicators. Check it out here: **[sami5001.github.io/gantt-charter](https://sami5001.github.io/gantt-charter/)**
</Image>

The slide in question is a Gantt chart, a horizontal bar chart that lays your project's tasks against time, so anyone can see what happens when, what overlaps, and which deadlines are looming. You can also indicate resources, and fancy paid software has more elaborate features that can easily be a tutorial or course on its own. If you have ever planned a project, you have probably drawn one. In academic life they are everywhere: in supervision meetings, in grant applications, and (the two that every Oxford DPhil student knows well) in the **Transfer of Status** and **Confirmation of Status** reports that mark your progress through the degree.

Here is the thing about Gantt charts though, as researchers, we are never really done with them. Every presentation, every report, every funding bid wants one. They are part of the academic stack. So it is worth getting the process of making them right. For years, I made them from scratch, and given my design focus, I was never happy with colouring excel cells to mimic one.

## The Keynote approach

My usual Gantt charts were made by hand in Apple Keynote. I am, for better or worse, particular about how things look, so I built my own design elements. Tidy bars, a consistent palette, aligned gridlines, careful typography. They looked good. I was proud of them.

They were also challenging to maintain. A Gantt chart is a picture of a plan, and plans change constantly. Move one deadline and you are dragging a dozen rectangles by hand, re-aligning everything, hoping you did not knock the spacing out by a pixel. Every update was manual, and every manual update was a chance to introduce a small, embarrassing inconsistency. I was spending real time on the _drawing_ of the chart when all I wanted was to change the _data_ behind it.

That is definitely the sign, in any workflow, that something should be automated. When the interesting decision (the plan) is cheap, and the mechanical execution (the picture) is expensive.

## Rebuilding it as code

So I rebuilt the whole thing in Python. The idea was simple, describe the plan as data, and let the computer draw the chart. Change a date in one place, regenerate, and the picture is always correct and always consistent.

The tool, which I called **Gantt Charter**, reads a small, human-readable YAML file that describes your project:

```yaml
project:
  title: 'DPhil Research Timeline'

config:
  palette: professional
  branding: true

tasks:
  - name: 'Literature review'
    start: 2026-01-05
    finish: 2026-02-13
    resource: 'Researcher'
    phase: 'Preparation'
  - name: 'Data collection'
    start: 2026-02-16
    finish: 2026-05-29
    resource: 'Researcher'
    phase: 'Fieldwork'

milestones:
  - name: 'Confirmation of Status'
    date: 2026-09-30
    description: 'CoS report submitted'
```

One command turns that into a finished chart:

```bash
python cli.py -i data/gantt_data.yaml -f pdf --paper a4 --orientation landscape -p professional
```

Under the hood it is a small stack of well-worn, dependable tools, each doing one job:

- `Plotly` is the charting engine: it draws the bars, axes, hover labels, and the interactive HTML version.
- `pandas` turns your YAML or CSV into a tidy table that the chart is built from.
- `NumPy` does the numeric work underneath: the date arithmetic and layout maths.
- `PyYAML` reads the friendly YAML config.
- `Kaleido`, driving a headless Chrome, renders the static PNG, PDF, and SVG exports.
- A **self-contained Oxford Plotly theme** carries the house style (the colours, fonts, and spacing) so every chart comes out looking consistent, with no external dependencies.

This was a genuine improvement. The charts were consistent, reproducible, and version-controllable. But it solved one problem and quietly introduced another.

## When code is its own kind of friction

Code-first is wonderful when you are building a careful, complex timeline. It is much less so when time is limited, you are about to finalise a presentation, and you just need _a chart_, now.

In those moments, it can be too much. Opening a text editor, remembering the YAML schema, getting the indentation right, activating a virtual environment, and running a CLI flag I half-remember. The input was too programmatic for a quick output. I had swapped the manual friction of Keynote for a different friction. The overhead of being a programmer every time I wanted a picture.

A tool that is only pleasant to use when you have ten minutes and your terminal open. But in the end, it is not a tool for everyone. And I wanted this to be useful to people who do not write Python at all.

## So I added a web interface

The fix was to put a friendly frontend on the same engine. A web app you can use straight from the browser, with **no installation at all**. It lives here:

**[sami5001.github.io/gantt-charter](https://sami5001.github.io/gantt-charter/)**

It works two ways, depending on the requirement:

- For a **complex chart**, you can import a CSV. There is also a CSV template that is available on the web app. Export the plan from a spreadsheet you are already keeping, drop it in, and it becomes a chart.
- For a **quick chart**, you can add tasks directly in the interface, no file needed.

A CSV is about as low-friction as data gets:

```csv
Type,Task,Start,Finish,Resource,Phase
task,Literature review,2026-01-05,2026-02-13,Researcher,Preparation
task,Data collection,2026-02-16,2026-05-29,Researcher,Fieldwork
milestone,Transfer of Status,2026-06-15,,,
```

The part I find genuinely useful is the **dynamic preview**. The chart updates as you type. Change a date, rename a task, switch the palette, and you see the result immediately, with no regenerate step and no guesswork. It closes the loop between editing the plan and seeing the picture, which is exactly the loop that was so tedious when designing one manually.

And when you are happy, exporting is easy, with several ways to do it (PNG, PDF, or SVG) so you are never locked into a single format. You can even switch between light and dark modes for using them in your presentations.

The web app is built with **Astro and React**, styled with **Tailwind CSS**, and hosted for free on GitHub Pages. It uses `PapaParse` to read CSV, `js-yaml` for the same YAML the Python tool understands, `SheetJS` for spreadsheet import, and `jsPDF` with `svg2pdf.js` to build the vector exports. Crucially, all of this runs **entirely in your browser**. Your project data is never uploaded anywhere. For anyone planning sensitive or unpublished work, that matters. You can even download the entire codebase and run it locally on your machine.

## The details I am quietly proud of

A timeline tool lives or dies by its small touches, so a few of the things I cared about:

- **Milestones are first-class.** They render as diamonds pinned along the top of the chart, with dotted guide lines and angled labels, picked out in Oxford Primary Health Care burgundy (`#8A1751`), a small nod to where the tool was born.
- **Twelve Oxford colour palettes**, from a restrained _professional_ to a _vibrant_ one, including a colour-blind-friendly diverging set and a _health_ set for clinical work.
- **The layout adapts to your data.** Margins grow to fit your longest task name and your milestone labels; the chart height scales with the number of rows; and the date axis chooses a sensible tick interval, from monthly through to half-yearly, based on how long the project runs. You should not have to fight the layout.
- **Recurring tasks** with the same name (case sensitive) share a single row, each drawing its own bar, which is handy for something like a weekly supervision meeting.
- **A single-day deadline** (a task that starts and finishes on the same date) renders as a diamond marker, so it never vanishes into a zero-width bar.
- **Exports are matched to purpose: **PNG for documents and slides, and PDF or SVG for publications and further editing in a design tool.

The result is something I actually reach for now: charts that look like they belong in a thesis or a grant application, made in the time it takes to type the plan.

## Why a small tool like this matters

Having gone through a DPhil, and after trying many tools to create Gantt charts, I am increasingly convinced that much of the friction in research is not in the hard, interesting problems. It is in the thousand small, repetitive tasks that surround them. Re-making the same chart, by hand, for the fifth time. Each one is minor; together they are a quiet tax on your attention. Tools that remove that friction give you back the thing that is actually scarce, which is focus. And there is no good reason for research outputs, even the humble project timeline, to be ugly or painful to produce. A little craft goes a long way.

**Gantt Charter** is open source under the MIT licence, and it is genuinely a tool I built for myself first. If you make Gantt charts, whether for a thesis, a grant, a project plan, or anything else, I would love for you to try it.

- **Use it in your browser:** [sami5001.github.io/gantt-charter](https://sami5001.github.io/gantt-charter/)
- **Read the code, open an issue, or contribute:** [github.com/sami5001/gantt-charter](https://github.com/sami5001/gantt-charter)

If you have ideas, find a bug, or want a feature, please send them my way -- just open an issue on GitHub. I find the best improvements have come from other people's needs that I would never have thought of myself. And if you know someone wrestling with a timeline in Excel at 1am, do them a kindness and share this with them.


A small, open-source tool for making publication-quality Gantt charts, born from years of hand-drawing research timelines in Keynote.

Writing

Why I built Gantt Charter