Structured Notes for Developers

I moved to Portugal at the end of 2024 and started keeping a daily note, mostly because I had lost track of where my time was going and got tired of guessing.

Keeping the note is easy. The problem shows up around month three, when you have ninety files of prose and no way to ask them anything. You can grep, which will find you the day you wrote the word "shoulder" and tell you nothing about the shape of the year. If you want to know whether you genuinely walked less this winter than last, prose will not answer, and neither will memory, which has opinions and edits accordingly.

So the notes need some structure in them. The trap is that most systems built for this put the burden of the structuring on you, up front, before the thought has even settled. You end up maintaining a task in one place, a journal in another, a habit tracker in a third, and a summary in a fourth, and the system starts asking for more care than the work it was supposed to support. That is the point where people quit, and they are right to.

What I wanted was a note that stays a note, with just enough machine readable residue left behind that I can ask it questions later. Plain Markdown files, one per day, a small amount of structure at the top, and a plugin doing the tedious part. That is the whole system, and the rest of this is how it fits together.

Instrument the day

Developers already understand this instinct in another context. You would not run a service with no metrics and rely on remembering how it felt last month. You instrument it, store the telemetry, and look at the dashboard when something seems off. Doing it to yourself sounds absurd right up until the graph shows a three week slide you had already explained away in your head.

The point is not to make every day measurable. It is to capture the parts of the day that are expensive to reconstruct later, in a format that will outlive whatever tool is currently fashionable.

Markdown suits that. John Gruber introduced it in 2004 so web writers could work in plain text and get HTML out of it,¹ and the part that matters here is that the source still reads like the thing it represents. A heading looks like a heading. A file you wrote in 2025 opens in anything, forever.

The setup

The system runs on Obsidian, which stores everything as plain .md files on disk. No proprietary format, no cloud dependency, no vendor holding your own thoughts. The files live in a vault, which is a folder, and plugins handle the rest.

Three community plugins and one of mine:

• Calendar by Liam Cain. A sidebar calendar that opens or creates the day's entry on click. Without it you are hand-creating 2025-03-14.md every morning, and that friction alone kills the habit inside a week.

• Tracker by pyrochlore. Reads YAML frontmatter and renders line charts, bar graphs and summaries. This is where weeks of logging become visible.

• Emoji Toolbar by oliveryh. A quick picker, which matters more than it sounds for the Labels feature below.

• Habsiad, which I wrote, and which does the tedious part. More on it below.

What a journal entry looks like

Every entry lives in JOURNAL/, named by date. The template is deliberately unambitious:

---
goodwork:
meditation:
workout:
cook:
book:
hydrated:
steps:
weight:
calories:
---
# MONDAY
## WORK:
###### Summary:

### Goals for Today:
- Goal 1
- Goal 2
- Goal 3
## LIFE:

### FOOD:
| Time      | MEAL | EST.CALORIES |
| --------- | ---- | ------------ |
| Breakfast |      |              |
| Lunch     |      |              |
| Dinner    |      |              |
| Snacks    |      |              |
### TODO:
Move real next actions to LIFE.md.

### Reflections:

The frontmatter is the queryable part. Those keys get filled in through the day, by hand or by sync, and Tracker graphs them over time. Everything below is freeform.

A template only has to be good enough to lower friction. If it tries to anticipate every possible future use, it becomes the problem it was meant to solve.

Habsiad: the glue layer

Habsiad is the piece I had to write, and it exists because of a specific gap in the tools I was already using.

Habitica is a habit tracker dressed up as a role playing game. Tick a box, get experience points, level up, take damage when you skip a day. It works, and I still use it. What it will not do is tell you what last month looked like. Completed days are not stored anywhere you can read them back, so the streak counter ends up being the only memory the thing has, and a streak is just a number that resets.

Todoist keeps its history, which is better, and then trips over something else: you cannot change the hour at which the day rolls over. It is always midnight. So if you sit down at half past one to write up the day you just finished, the app has already filed it under tomorrow. Finishing before midnight is perfectly good advice and I have never managed it for more than a fortnight at a stretch. Superproductivity gets closer than either, and has enough deep quirks that bending it into the shape I wanted stopped being worth the afternoon.

The common thread is that all of them keep the record on your behalf, and a Markdown file does not care what time it is. 2025-03-14.md is that day's note because I put it there, whenever I got to it.

So Habsiad syncs completed Habits, Dailies and TODOs out of Habitica and into the journal entry's frontmatter. One keystroke at the end of the day, and every tracked behaviour becomes a permanent, graphable data point sitting in a file I control.

The Habitica half is optional. Habsiad's Retrotagger logs habits and dailies straight into any entry, past or present, and the data format is identical either way. The whole system works without ever creating a Habitica account.

The Frontmatter Glossary maps Habitica habit and daily names to YAML keys in the template. The result is not glamorous: a row of booleans and numbers at the top of every file that any tool can read. That is exactly why it works. The daily note is still a daily note. Habitica helps with behaviour, Tracker draws the charts, Habsiad moves data between them, and the file on disk stays the thing I can open, search and understand without any of them.

Data Quality Diagnostics scans every entry and reports missing keys, empty entries and inconsistencies, which catches gaps before they quietly compound into a misleading trend line.

Labels: track anything with an emoji

This is the feature that made the system stop feeling like a template. Anywhere in an entry, write an emoji, a colon and a number:

Drank a lot of water today `💧: 8`
Indoor temperature was brutal `🌡️: 31`
Read before bed `📖: 45`

Habsiad aggregates labels across every entry chronologically. Click one and you get a timeline of every occurrence with its value. No schema change, no configuration, no predefined categories.

This works because the data lives inline with the writing. You do not context switch into a tracking app. You mention it the way you would mention it in conversation, and the structured version extracts itself later.

That matters more than it sounds. Most personal systems fail at the moment of capture. They ask for precision before the thought has settled. Inline labels let the note stay loose and still leave something machine readable behind.

Logs: specialised journals inside the journal

Logs use Obsidian's callout syntax for categorised entries that Habsiad collects across the whole vault:

> [!WORKOUT] #### Morning run
> 5K in 25 minutes. Shoulder still tight from yesterday.

> [!DREAM] #### The one with the server room
> Debugging a production outage in a building that kept
> adding floors. Classic stress dream.

Define any type you like. [!WORKOUT], [!MEETING], [!DREAM], [!IDEA]. Habsiad groups them chronologically and gives each category its own timeline. A workout journal, a dream journal and a meeting log, without maintaining separate files for any of them.

Separate files are not free. Separate categories are not free. Every new place to put information creates a small decision tax. If a category is useful enough, fine. If it exists only because the tool made it cheap to create categories, it should not exist.

What the graphs actually caught

The daily cost is low. Open today's note, fill the template in as the day happens, sync at the end. Five minutes of active effort on an ordinary day.

The value is in what you cannot argue with later. Two metrics have caught me out.

The first was steps. I had a story about walking everywhere, which was true when I arrived in Portugal and had quietly stopped being true some months later. The graph did not care about the story.

The second was commits. I had been telling myself I was still working on my own projects most evenings. The commit history disagreed for most of a month, and the frontmatter agreed with the commit history rather than with me.

Neither of those was recoverable from memory, because memory edits. It rewrites the average toward whatever you currently believe about yourself. A file written on the day does not.

The signal is the point, not the dashboard. A graph is only useful if it changes what you notice. A template is only useful if it makes the next entry easier. A plugin is only useful if it removes a small piece of repeated labour.

Why Obsidian

Org mode in Emacs is more powerful than any of this and carries a learning curve that doubles as a barrier to consistency. Notion stores your data on someone else's server, which fails the same test Habitica fails.

Obsidian is not open source. It is a proprietary application with a paid sync service. The files it produces are plain Markdown on a local filesystem, so if Obsidian disappears tomorrow the entries stay readable and portable, and the sync service is optional. Git works fine instead.

The plugin ecosystem is what makes the difference. Calendar, Tracker, Emoji Toolbar and Habsiad together produce a workflow no single app ships, each doing one thing, with Habsiad as the messy orchestration layer that makes them behave like one system.

Nobody needs this exact setup. What is worth stealing is the question underneath it: what are your notes for? "Remember things" is too vague to design against. Remember what, for how long, to make which decision easier, to notice which pattern, to avoid repeating which mistake?

Getting started

1. Install Obsidian and create a vault.

2. Install the Calendar, Tracker and Emoji Toolbar plugins.

3. Install Habsiad and follow the Getting Started guide.

4. Create a JOURNAL/ folder and a template with the frontmatter keys you want.

5. Click today's date in the Calendar sidebar and start writing.

Consistency beats completeness. A half filled entry every day is worth more than a detailed one every week, because the trend line is the product and a trend line needs points.

Start smaller than you think. One folder. One template. A handful of fields. If a field does not change your behaviour or help you understand something later, delete it. Notes should earn their structure.

Updated August 2026. The vault has been running since I moved to Portugal in late 2024. The oldest entries are the least interesting to read and the most useful to have.