Guide
Markdown project management: projects, tasks and hours as plain text files you own.
Markdown project management means keeping each project as an ordinary Markdown file on your own disk, with tasks as checkbox lines, dates and fields written into those lines, and the tools reading the files instead of a database. This page explains how it works, what a project file looks like, the conventions worth adopting, the three ways to run it, and where plain text stops being enough.
What Markdown project management is
A project is a text file. Its tasks are lines that start with a checkbox, - [ ] or - [x]. A due date, a priority, an estimate or a client sit on the same line in a small, readable notation. Notes go under the task as indented lines. Metadata about the whole project, such as its status or its client, sits in a short block at the top of the file called frontmatter. Everything a project tool would keep in its database is written into files you can open with any editor, search with any search tool, and keep for decades.
The tools, whether a plugin, a script or an app, read those files and draw views over them: a board, a calendar, a timeline, a list of what is due today. When you move a card on the board, the tool rewrites one line in the file. The file stays the source of truth; the views are disposable.
That is the whole idea. It is older than Markdown itself, going back to plain-text to-do lists and the todo.txt format, and it has returned because the alternatives now put every project you have ever run inside someone else's account.
Why people move their projects into plain text
The reasons repeat in every thread on the subject. The first is ownership: a Markdown file is yours in the plainest sense, on your disk, readable without a login, exportable without an export. The second is longevity: a file written today will open in ten years, which no cloud tool can promise. The third is that text composes with everything you already have: search, version control, backups, scripts, and now the AI assistants that read Markdown natively and write it fluently.
There are quieter reasons. A plain-text project cannot be rate-limited, and it works on a plane. Nothing is charged per seat, because there are no seats. And a text file is honest about scope: a project with eleven tasks is eleven lines, not a workspace with forty empty custom fields.
- Your projects, hours and invoices are files on your disk, not rows in a vendor's database
- They open in any editor, in Obsidian, in a terminal, and in whatever replaces all three
- Git, Time Machine and a search tool already work on them
- Language models read and write Markdown without a connector
- Offline by nature, and nothing is priced per person
What a project looks like as a Markdown file
This is the sample project the nokko Mac app writes into a new workspace, trimmed to its bones. The frontmatter names the client, the dates and two custom columns. Under two headings are the tasks: one finished with its completion date, one in progress with a note, two subtasks and a logged session, one waiting on the client, a milestone, and two scheduled for later. Every symbol has a meaning, and every meaning survives being opened in a different program.
Read it top to bottom and you know where the job stands. That is the test of the format: a project file should be a status report when nobody is running an app.
---
type: project
status: active
client: Bakehouse
start: 2026-11-01
due: 2026-11-29
columns:
- "Budget: number"
- "Stage: select(Discovery, Design, Build, Launch)"
---
# Bakehouse Website
## Design
- [x] Kickoff call with the baker โ
2026-11-02
- โฑ 2026-11-02 10:00-11:00 (1h) โ kickoff call
- [/] Homepage design [Stage:: Design] [Budget:: 400] [est:: 6h]
- Two directions so far: warm/rustic and clean/modern
- โฑ 2026-11-06 09:15-12:30 (3h15m) โ first pass at the hero
- [ ] Pick a typeface pair
- [ ] Mock up the hero section
- [>] Logo files from the client
- [ ] Design sign-off [est:: 45m] ๐ฏ ๐
2026-11-15
## Build
- [ ] Set up hosting [Stage:: Build] [Budget:: 150] [est:: 2h] ๐
2026-11-09
- [ ] Build the menu page [est:: 4h] โณ 2026-11-11
- [ ] Launch checklist [est:: 1h30m] ๐
2026-11-28The conventions worth adopting
Markdown has no rule for dates or priorities, so every tool invents one, and the point of plain text is lost the moment two tools disagree. Two conventions have become the common ground, because the largest community of Markdown task users, Obsidian's, settled on them: the Obsidian Tasks notation for the task line, and Dataview inline fields for anything else you want to query.
Adopt them even if you never open Obsidian. They are documented, stable, and read by more tools every year. nokko reads and writes both, so a vault opens in nokko and a nokko workspace opens in Obsidian; the Obsidian Tasks and Dataview reference in the guide lists every mark nokko understands, and the nokko-format repository on GitHub carries the same specification with a sample workspace you can open in any of the three.
- One file per project. Folders group projects into spaces or clients; a file without tasks is a doc
- Status in the checkbox:
[ ]to do,[/]in progress,[>]waiting,[x]done,[-]cancelled - Dates as emoji followed by ISO dates: ๐ซ start, โณ scheduled, ๐ due, โ done
- Priority marks (โซ ๐ผ ๐ฝ), a repeat rule (๐ every month), and ๐ฏ for a milestone
- Anything queryable as an inline field:
[est:: 6h],[Budget:: 400],[Stage:: Design] - Time logged as a โฑ line under the task it belongs to, with the date, the span and a note; the time entry format is specified down to the character
- Project metadata in frontmatter: type, status, client, start, due, and the columns the list view should show
Three ways to run Markdown project management
The first way is an editor and discipline. VS Code, a terminal, or any Markdown editor, plus the conventions above. You get the files and nothing else: no board, no calendar, no timer, no sum of hours. It works for one person with few projects, and it is where most people start.
The second way is Obsidian with plugins. Obsidian is a Markdown notebook with a plugin ecosystem; with Tasks, Dataview, a kanban plugin and, since 2025, Obsidian's own Bases tables, a vault becomes a capable project tool. The cost is assembly: each view is a plugin or a query to write and maintain, and the phone needs a sync service. The Obsidian project management guide on this site goes through that stack piece by piece.
The third way is a dedicated app that treats the files as its database. This is what nokko is: a native Mac app, with an iPhone app, that opens a folder of Markdown files and draws a timeline, a board, a list, a calendar, a Today screen, a timer and invoices over them, writing back only the characters you changed. It does the assembly so you do not, and it adds the two things no plugin stack does well, time tracking and invoicing, which is what freelancers and small studios need the projects for in the first place.
Where plain text stops being enough
Markdown project management is a bad fit for some teams, and the people who sell it should say so. A file has no permissions: anyone who can read the folder can read every project. There are no automations, no approval chains, no client portal, no per-type workflows, no payment links on invoices. Reporting across fifty projects means a tool that reads fifty files, which is fine for a studio and wrong for a department.
If your work needs roles, sprints with story points, integrations with a dozen SaaS tools, or a vendor to call at three in the morning, stay with the cloud tool. The Markdown approach wins for one person or a small group who bill for their time, want their records to outlive their software, and would rather own a folder than administer a workspace.
Sharing Markdown projects with a small team
Files share the way files always have: through a repository or a server. A private Git repository is the natural home for a folder of Markdown, because every change becomes a commit in someone's name and a deleted file is never gone. The alternative is a server you already pay for, reached over SFTP, or, for one person's own devices, iCloud.
The hard problem is two people editing one file at the same time. The honest answer is to keep both versions, mark the conflict, and let a person decide, rather than silently merging task lines. That is what nokko does across all three routes; the sync guide compares them. Services that replace files underneath an app, such as a synced Dropbox folder, are the one place to avoid keeping a live workspace.
- A private GitHub repository: sign in with a code, every change a commit in your own name, teammates invited by username
- Your own SFTP server: a VPS, a NAS, a storage box or a spare Mac, with a thirty-day trash for deletions
- iCloud between one person's Mac and iPhone
- Conflicts keep both versions on every machine; nothing is merged behind your back
Markdown project management with nokko
nokko is a native Mac app, with an iPhone app beside it, built around the file format described on this page. Point it at a folder and every Markdown file with tasks is a board; the same files appear as a Gantt timeline, a list with the columns you declared, a month calendar, an overview per folder and a Today screen whose order you set by hand. A timer on any task writes a โฑ line under it, and at the end of the month an invoice is drafted from those lines with rates, VAT and sequential numbers, saved as another Markdown file and printed to PDF.
It is free to download and reads everything forever; editing is a subscription or a one-time purchase through the App Store, one purchase for Mac and iPhone. It needs macOS 26 on Apple silicon and iOS 26. There is no Windows, Android or web version, and an iPad app is planned for version 1.2. If you use Obsidian, keep it open: nokko for Obsidian users explains how the two share a vault.
The three ways, side by side.
What each approach gives you over the same folder of Markdown files.
| Capability | Editor + conventions | Obsidian + plugins | nokko |
|---|---|---|---|
| Files stay plain Markdown | Yes | Yes | Yes |
| Board and calendar views | No | With plugins | Yes |
| Gantt timeline | No | With a plugin | Yes |
| Timer that writes into the task's file | No | With a plugin | Yes |
| Invoices drafted from logged hours | No | No | Yes |
| Phone app | Any editor | Obsidian mobile + a sync service | iPhone app |
| Sharing with a teammate | Git by hand | Git by hand or a sync service | Own GitHub, SFTP or iCloud, built in |
| Notes, links and a graph | Plain text | Yes | Docs only; Obsidian is the notebook |
| Windows, Android, web | Yes | Yes | No |
Swipe sideways for the other columns.
The things people ask.
Is there a Markdown-based project management app for Mac?
Can I keep a Gantt chart in Markdown?
Is there a Markdown project management template?
Does Markdown project management work with Obsidian?
Can a team use Markdown files for project management?
What about time tracking and invoicing in Markdown?
Is there a version for Windows or Android?
Free to read, on your Mac and your iPhone.
Download it, open a folder, and read everything your studio has planned. Subscribe when you are ready to edit; the first 14 days are free, and one subscription covers both.