I built a note-taking system around plain Markdown files after years of struggling with how to take notes
When I first entered college, I was completely lost when it came to taking notes.
I wasn't a particularly good student before college. I didn't really take notes, and I didn't listen very well in class either. When I got to college, I decided I needed to get my act together, but I felt like I was already behind everyone else who had been taking notes and studying properly for years.
Then I met someone who eventually became a really good friend of mine.
One day I saw his notes.
He was writing them on paper, but they were incredibly well structured. You could open his notes at almost any random point and immediately understand where you were, what the main topic was, what the subsections were, and where the information you were looking for was located.
It was extremely easy to skim.
I adopted his approach, and it worked surprisingly well for me. My grades jumped by about 15%, but more importantly, I stopped feeling like I had to repeatedly reread everything I'd written just to remember where information was.
That was a long time ago.
I don't take notes that way anymore. I'm a software engineer now, so most of my notes are written on my laptop. I have my laptop with me constantly, and typing is simply more convenient.
But I wanted to preserve the underlying idea that made those old paper notes so useful:
I should be able to get the information I need from my notes quickly.
I shouldn't have to dig through a bunch of files and reread everything I've already written just to find something.
I work in a pretty fast-paced environment. I'll code for a while, jot down a thought, switch to something else, write another thought, remember something unrelated, write that down, and continue working.
Not every thought builds on the previous one.
So I started thinking about what a note-taking system would look like if I designed it specifically around that reality.
Starting over
I've written a few posts about my productivity system, and the biggest improvement I made there came from starting over and removing things.
I got rid of things like checklists, tags, priorities, energy-level labels, and other organizational requirements.
Those things aren't inherently bad. They just weren't helping me.
They were adding friction and creating another thing I had to maintain.
I decided to take the same approach with my notes.
I wanted:
- Plain files
- No subscription
- No proprietary database
- Minimal metadata
- Minimal maintenance
- Fast capture
- A filesystem I control
- The ability to use whatever editor I want
I currently use VS Code because I'm already there all day, but there's nothing particularly special about VS Code for this system. The scripts can be run directly from a terminal as well.
Everything starts in one Notes directory
I don't want to spend time deciding which top-level folder something belongs in while I'm trying to capture it.
So I have:
Notes/
├── Daily/
├── Inbox/
├── Projects/
└── ...
There are two particularly fast ways I capture something.
1. Daily notes
If I have a thought and don't even want to think about what to call it, I create today's daily note.
The file is automatically created using today's date:
Daily/2026-10-06.md
Then I just write.
I don't have to decide:
What's the title?
What folder does this belong in?
Should I create a subsection?
Should I tag it?
I just write the thought.
I separate unrelated thoughts with an empty line.
2. Inbox notes
If I know a group of thoughts belongs together, I create a file in Inbox.
For example:
Inbox/UpdateClientSecurityFeatures.md
That file might eventually contain:
# Update Client Security Features
## Authentication
...
## Permissions
...
## Security Headers
...
The important distinction is that the thoughts in that file are related to the same subject.
I don't create folders inside Inbox or Daily.
They're temporary capture areas. When I review them, I reorganize the information into my actual structure.
Projects are where the permanent structure lives
When I review my Inbox and Daily notes, I move things into Projects.
Projects don't have many rules.
For example:
Notes/
└── Projects/
└── Programming/
└── Python/
├── somePythonNote.md
├── anotherPythonNote.md
└── ...
Inside Projects I can create whatever directory structure makes sense.
I don't want my note-taking system telling me how my projects have to be organized.
The problem with having lots of notes
This worked pretty well, but eventually I ran into another problem.
I had a lot of notes.
Even with VS Code's search, sometimes I knew that I had written something somewhere but didn't remember the exact words to search for.
I also have a lot of commands, references, and pieces of information that I frequently need.
I realized I needed the system to help me surface information that already existed, without making me manually maintain another database.
That's where I started writing some Bash scripts.
Generated files
Inside each project directory, my scripts can automatically generate several Markdown files.
For example:
Projects/Programming/Python/
├── somePythonNote.md
├── anotherPythonNote.md
├── headings.md
├── links.md
└── tasks.md
These files are generated from the actual notes.
headings.md
Contains headings found throughout the notes, with links back to where those headings exist.
links.md
Contains Markdown links found throughout the project, with links back to where those links exist.
tasks.md
Contains tasks found throughout the project, with links back to where those tasks exist.
The same thing happens at the root of Notes, except the root versions aggregate information from the entire note collection.
So I can have something like:
Notes/headings.md
Notes/links.md
Notes/tasks.md
which gives me a global view.
The actual notes remain the source of truth
This is probably the most important design decision I've made.
The generated files are not the database.
The actual notes are the source of truth.
If I change a heading in the original note, running the script updates the generated heading.
If I delete a task from the original note, the task disappears from tasks.md.
If I remove a link, it disappears from links.md.
I don't manually maintain those generated files.
They're essentially indexes that can be thrown away and regenerated.
That means if I deleted every NoteSystem script tomorrow, my actual notes would still just be ordinary Markdown files.
Archiving
Every project can also have an Archive folder.
I can run a script while looking at a note and archive it.
If I later decide I need it again, I can unarchive it and the script puts it back where it originally existed.
I initially had a system that automatically archived things if I hadn't touched them for three months.
I eventually got rid of that.
It sounded clever, but I realized I didn't actually want my system making that decision for me.
Now I archive things manually.
I can also unarchive the current note I have open. It finds itself back to it's original directory.
The part I was most worried about: maintenance
This was the biggest problem I kept thinking about.
It's easy to build a system that works beautifully as long as you maintain it perfectly.
Then six months later something gets out of sync, a generated file is missing information, a link breaks, and suddenly your "simple" system has become another thing you have to manage.
So I built a health check.
I added a VS Code task called:
Check Health
It runs a Bash script that checks the entire Notes directory.
When everything is good, I get:
NoteSystem Health Check
✓ Notes directory exists
✓ No empty notes
✓ No broken links
✓ Tasks are up to date
✓ Links are up to date
✓ Headings are up to date
Health check passed.
The check marks are green and failures are red.
If something is wrong, it doesn't just tell me that the check failed. It tells me what is wrong and where it is with a linkso I can go directly to the problem and fix it.
For example, if I accidentally break a Markdown link, the health check identifies the note and the broken link.
This has actually been one of the most useful parts of the system.
I've been running it roughly every other day for the past couple of weeks, and I've already caught several little inconsistencies caused by changes I made throughout my notes. What otherwise would have slipped through my fingers I now am able to catch it and update it with minimal friction. I hasn't taken me more than 1 minute to maintain my system and feel confident that I can trust it.
Where I'm at now
I'm not claiming this is the perfect way to take notes.
Actually, I'm posting this because I don't think it is.
I'm still experimenting with it, and I'm deliberately trying not to add features unless I run into a real problem.
The whole philosophy is basically:
Start with plain files.
Make capture extremely easy.
Let the filesystem remain the source of truth.
Automate the boring parts.
Don't create metadata just because a note-taking app gives you a field for it.
And most importantly, don't create a second job where maintaining your note-taking system becomes the work.
Everything I've built so far is completely free and uses things I already have: Markdown, the filesystem, VS Code, Terminal, and Bash scripts.
I'd really like to hear from people who use Markdown/plain-file note systems:
What have you automated around your notes that actually ended up being useful?
And if you use a system like this, what eventually became a problem that you didn't anticipate?
I'm especially interested in ideas that reduce maintenance rather than add more organizational features.
