How to manage projects with Markdown and Mermaid Gantt charts

Project management tools are convenient, but they come with a monthly fee, your data is locked inside the service, and no one knows whether that service will still be around in a few years.

Text files, on the other hand, will still open 30 years from now. This article shows you how to track project progress with nothing but Markdown and Mermaid.

Why manage projects in plain text

Opens in any editor. You’re not tied to a particular app
You can see the diffs. Keep it in Git, and you have a record of who changed what, and when
It’s searchable. Finder or grep—it works like any ordinary file
Easy to hand to AI. These days, this is the biggest advantage of all (more on this below)

How to write a Mermaid Gantt chart

Mermaid is a syntax for drawing diagrams with text. You write it in a Markdown code block marked mermaid.

```mermaid
gantt
    title Website relaunch
    dateFormat YYYY-MM-DD
    axisFormat %m/%d
    excludes weekends

    section Prep
    Gather requirements   :done,    req,  2026-09-01, 5d
    Set design direction  :done,    des,  after req, 4d

    section Build
    Build home page       :active,  top,  2026-09-12, 7d
    Build inner pages     :         sub,  after top, 10d

    section Launch
    Internal review       :crit,    rev,  after sub, 3d
    Go live               :milestone, m1,  after rev, 0d
```

There isn’t much to remember.

Syntax	Meaning
`dateFormat YYYY-MM-DD`	Date format (declare it first)
`section Name`	Groups tasks into phases
`:done,`	Completed task (gray)
`:active,`	Task in progress (darker color)
`:crit,`	Critical task (red)
`:milestone,`	Diamond-shaped marker for a deadline
`after req`	Starts after another task (ID `req`) ends
`5d` / `2w`	Duration (days, weeks)
`excludes weekends`	Leaves Saturdays and Sundays out of the day count

Common pitfalls

If you forget dateFormat, dates won’t be parsed
A : inside a task name causes an error
after refers to the ID, not the task name (req, top and so on in the example above)

A simple routine for tracking progress

Elaborate routines don’t last. These three habits are all you need.

Make one overview note per project. The goal, the people involved, where things stand, what’s next, and the Gantt chart
Update it only once a week. Change :active to :done and fix the dates of tasks that slipped. It takes five minutes
Write small tasks as checklists. Write them like - [ ] Send the draft, and you can see unfinished items at a glance

The Gantt chart is for seeing the overall shape; day-to-day task management is the checklist’s job. Being able to keep both in a single file is what makes this approach work.

Where you can view the diagrams

Mermaid renders as is in Markdown on GitHub and GitLab. If you want to see it as you write on your own Mac, you need an editor that supports Mermaid.

Markdocx has Mermaid built in, and rendering happens entirely on your Mac. One app takes you all the way to exporting the finished document as Word or PDF
Orviss includes a Gantt chart in its Project Overview template from the start. Just add lines to start tracking progress

Let an AI agent read it

This is where managing in text really pays off.

AI agents like Claude Code, Codex and Cursor can read and write the files in a folder. If your project materials are plain Markdown on your local disk, just point the agent at that folder, and requests like these

“Summarize where this project stands in five lines”
“Pick up the unfinished tasks from last week’s meeting notes and add them to the checklist”
“We’re three days behind, so redo the dates in the Gantt chart”

will just work. No special integration setup, no API keys. Your project folder simply becomes the AI’s outboard brain.

Orviss is an app built with this way of working in mind. In project and date folders, you can keep not only Markdown notes but also ordinary files, web pages and emails together. Everything is plain local files, so changes the agent makes show up on screen right away. The Mac version is available now, and iPhone and iPad versions are coming soon.

→ Learn more about Orviss

Summary

Mermaid’s gantt is a simple syntax with fewer than 10 things to remember
One overview note plus a weekly update keeps progress tracking going
Keeping things in text means you can hand them straight to an AI agent as context

Information