Essentials

Note Types Matter

A manifesto for better Markdown systems#

In this manifesto, I want to convince you that note types matter a LOT more than most people think.

Not only for tools. Not only for AI. And certainly not only for people who love structure.

Note types matter because they make Markdown systems easier to use, easier to trust, easier to improve over time and easier to scale.

Note types are not bureaucracy.

They are how plain-text systems stay clear, reliable, and useful as they grow.

The problem is that most Markdown note systems leave too much unsaid.

A note is just "a note". Maybe it belongs in a certain folder. Maybe it needs certain properties. Maybe it should link to a parent. Maybe it should contain a few sections. Maybe there is a template somewhere. Maybe there are rules. Maybe people are just expected to know.

That approach works for a while.

Then the system grows. Then the cracks show. Then trust goes down.

Notes end up in the wrong place. Important metadata goes missing. People create multiple versions of the same thing. Links break. Queries become fragile. Automation gets risky. Everyone has to keep the structure in their head. And AI wastes tokens.

We want better than that.

Why this matters for people#

First and foremost, note types improve the user experience.

When a note has a clear type, people know what it is, why it exists, where it belongs, and how it should connect to the rest of the system. That removes guesswork. And that's a huge deal.

It means:

better apps
better tools
better templates
better forms
better defaults
better validation
better auto-completion
better consistency
better automation
less friction when creating or editing notes
more confidence that the system still makes sense months later

This is NOT about turning writing into data entry.

Quite the contrary. Good structure gives people more freedom, because it removes avoidable confusion. When the basics are clear, you can focus on thinking, writing, connecting ideas, and getting actual value from your notes.

The good news is that note types improve reliability without taking away what people love about Markdown: plain text, portability, longevity, and control.

File over app#

There is another idea behind all of this, and it matters a LOT: file over app.

If you want your notes to last, then the files need to matter more than the app you happen to use today. The app can help you write, search, navigate, publish, and automate. Great. But the files should remain yours. Readable. Portable. Reusable. Durable.

And that has a very important consequence.

If files come first, then structure has to live with the files too.

Not hidden in app code/behavior. Not trapped in plugin settings. Not buried in a database. Not left as tribal knowledge for people and AI to guess their way through.

The thing is, a pile of files without clear structure is only half the story. Yes, the files are still there. But if their meaning depends on one specific app, one particular workflow, or one person's memory, then the system is still weak.

This is why note types matter so much.

Clearly defined note types give files durable meaning. They make it possible for another tool, another team member, or another AI assistant to understand the system without starting from scratch. Apps will change. Plugins will come and go. But the files, and the structure that explains them, can remain.

Why this matters for tools and AI#

Tools and AI need clarity too...

A validator should not have to guess what a note is by looking at its file name or folder.
An editor should not have to guess which fields to suggest.
A generator should not have to hardcode a structure.
An importer should not have to guess what should go where.
And AI certainly should not have to reverse-engineer a system from vague prose and half-baked conventions.

When note types are explicit, everything gets simpler.

Tools can:

inspect systems directly
validate data reliably
scaffold notes safely
auto-complete fields and links
explain errors clearly
query collections with confidence
generate better interfaces
support migration, refactoring, and reporting with far less risk
...

AI can:

understand what each note is for
follow the rules without inventing new ones
ask better questions
make fewer mistakes
help users faster and more safely

The thing is, good automation depends on clear contracts. So does good AI assistance. Without those contracts, software guesses. And guessed structure is weak structure.

What clearly defined note types make possible#

Clearly defined note types make it possible to build Markdown systems that are both flexible and dependable.

They give us systems that can:

organize themselves more consistently or even on autopilot
stay readable as plain text, remain portable & interoperable
expose their structure for introspection
support strong validation
power smarter interfaces
grow without collapsing into chaos

Once the system is described clearly, end users get much better experiences. Think of validation that catches mistakes early. Think of auto-completion that suggests real values. Think of templates that are actually useful. Think of safer edits, fewer broken links, better queries, and tools that can help without guessing all the time.

That is good for individuals. That is good for teams. And that is VERY good for AI too.

This is for the community#

This specification is not about making Markdown rigid or unpleasant to use. It's about helping the community build better Markdown-based note-taking systems.

Systems that stay open. Systems that stay portable. Systems that stay readable. Systems that stay human. Systems that tools can understand. Systems that people can trust. Systems where files come first, and apps remain replaceable.

If you care about systems that still work after months or years of growth, then structure matters. And if structure matters, then note types matter.

Start simple. Avoid unnecessary complexity. But make the structure explicit. Write down your note types. Define the rules. Let tools validate them. Let users benefit from better defaults. Let AI help from a place of clarity instead of guesswork.

Conclusion#

At the end of the day, note types are about care.

Care for the people who create notes. Care for the people who read them later. Care for the teams that share systems. Care for the tools that support all of that.

I strongly believe that the community deserves systems that do more than store text. We can build systems that remain simple on the surface, while being clear, consistent, and dependable underneath. Systems built around files we control, rather than structure locked inside apps.

If you care about better note-taking, better tools, and better user experience, then take note types seriously.

Define them. Use them. Validate them. Improve them over time.

That's how we make Markdown systems easier to use, easier to trust, and easier to grow.

That's the promise behind TypedMark.