All posts

Build Your Personal Knowledge Base with Markdown

Create a future-proof personal wiki with plain markdown files and folders. Learn why portability beats proprietary apps, and how to structure your knowledge base for longevity.

Build Your Personal Knowledge Base with Markdown

Years ago, I tried Evernote. Then OneNote. Then Roam Research. Then Notion. Each promised to be my "second brain." Each was beautiful, powerful, and offered compelling reasons to trust it with everything I'd learned.

But I kept worrying: What if the company gets bought? What if they change the pricing model? What if they shut down? What if I can't export my data in a usable format?

So I switched to markdown. Now my knowledge base is just folders and files on my Mac. It's not fancy, but it's mine, and it'll be readable in 2050.

Why Markdown Wins for Knowledge Management

Proprietary note apps are seductive. They offer beautiful UIs, search, tagging, and sync. But they come with tradeoffs:

Lock-in: Your knowledge lives in their database, in their format. Export usually works, but it's lossy. Formatting breaks. Relationships vanish.

Fragility: What happens if the company pivots? Evernote has survived, but how many startups promised to be your "AI-powered knowledge companion" and then shut down?

Vendor control: They set the pricing. They decide which features matter. They can change the UX whenever they want.

Format obsolescence: Will Notion's proprietary format be readable in 20 years? Probably not. A markdown file written in 2006 is readable today and will be readable in 2046.

A plain markdown knowledge base avoids all of this. You control the format, the structure, the storage. You can read it with any editor. You can search it with grep. You can back it up however you want.

The Folder Structure

Keep it simple:

knowledge/
├── career/
│   ├── interviews.md
│   ├── salary-negotiation.md
│   └── learning-goals.md
├── technical/
│   ├── golang/
│   │   ├── concurrency-patterns.md
│   │   ├── testing-best-practices.md
│   │   └── error-handling.md
│   ├── system-design.md
│   └── databases.md
├── health/
│   ├── sleep.md
│   ├── exercise.md
│   └── nutrition.md
├── finance/
│   ├── tax-tips.md
│   ├── investing.md
│   └── retirement-planning.md
├── reading/
│   ├── 2025-books.md
│   ├── article-notes.md
│   └── quotes.md
└── projects/
    ├── openmark-marketing.md
    └── home-automation.md

This structure is:

  • Browseable: You can navigate with Finder or the file system
  • Searchable: grep works across all files
  • Versionable: Put it in Git for history
  • Portable: Copy the entire folder to a new Mac, it still works
  • Tool-agnostic: Any editor can open it

The Individual File Format

A single knowledge note is typically a markdown file with metadata and sections:

---
title: Golang Concurrency Patterns
date: 2026-02-25
tags: [golang, concurrency, patterns]
---

# Golang Concurrency Patterns

## Goroutines vs Threads

[Notes here]

## Channels

[Notes here]

## Select Statement

[Notes here]

## When to Use What

[Summary here]

---

Related: [[golang-error-handling]], [[system-design]]

The YAML frontmatter (date, tags) is optional but useful if you later want to build scripts to query your knowledge base.

How to Use Your Knowledge Base

As a Personal Reference

Forget something about a language you used a year ago? Grep for it:

grep -r "goroutines" knowledge/technical/golang/

Instant answer, in your own words.

For Long-Form Learning

When learning something new, create a file and take notes as you go. Don't copy-paste tutorials verbatim. Write in your own words. This deepens understanding.

For Decision Logging

Before a big decision (career move, technology choice, purchase), document your thinking:

# Should I learn Rust?

**Date:** Feb 25, 2026
**Reason:** Considering using Rust for a new project

## Pros

- Memory safety without garbage collection
- Good performance
- Strong type system
- Growing ecosystem

## Cons

- Steep learning curve
- Compilation time
- Smaller ecosystem than Python/Go

## Decision

Not yet. Go is a better fit for this project's timeline.

Six months later, review that file. You'll remember exactly why you decided. It's invaluable.

As a Public Blog

If you're comfortable, publish parts of your knowledge base. Convert a few markdown files to HTML and host them. Your knowledge helps others, and you get feedback.

Comparing with Obsidian and Proprietary Apps

Obsidian

Obsidian is excellent. It's built on markdown files in local folders, giving you the best of both worlds: local storage with a beautiful UI.

Obsidian pros:

  • Beautiful graph visualization
  • Elegant linking (backlinks, unlinked mentions)
  • Plugins and customization
  • Still uses markdown under the hood
  • Offline-first

Obsidian cons:

  • $40 desktop license (though free version works)
  • UI lock-in (even though files are markdown, the app has its conventions)
  • Reliance on Obsidian for advanced features

The choice: If you want a polished UI with markdown storage, use Obsidian. If you want maximum simplicity and portability, use plain markdown files + your editor of choice.

Notion, Roam, OneNote, Evernote

These are proprietary. Beautiful, yes. But your knowledge lives in their format. Use them for collaboration or specific workflows, but don't trust them as your primary knowledge base.

Adding Searchability

Plain markdown is searchable with grep, but you can do better:

# Simple: search all files for a term
grep -r "concurrency" knowledge/

# With context: show 3 lines before and after
grep -r -C 3 "concurrency" knowledge/

# Case-insensitive search
grep -ri "golang" knowledge/

If you want a nicer interface, tools like fzf or ripgrep work beautifully with markdown folders.

Or build a simple Python script to index frontmatter and search by tags:

import os
import frontmatter

knowledge_dir = "knowledge"
for root, dirs, files in os.walk(knowledge_dir):
    for file in files:
        if file.endswith(".md"):
            path = os.path.join(root, file)
            with open(path) as f:
                post = frontmatter.load(f)
                if "golang" in post.metadata.get("tags", []):
                    print(f"{path}: {post['title']}")

Syncing and Backups

Since your knowledge base is just files, you have options:

iCloud Drive: Sync to iCloud, have it on all your Macs and iPad. Apple keeps 30-day version history.

Git + GitHub: Push to a private GitHub repo. Full version history, and you can access it from anywhere.

Backblaze or Glacier: Set up automated backups to S3 or cold storage. Complete disaster recovery.

Synology NAS: If you're serious, a network drive with automated versioning gives you local backup + off-site redundancy.

The Compounding Return

Here's what happens over months and years:

  • You write a note about React hooks. Later, you link to it from a note about web development.
  • You build a habit of writing decision logs. Eventually, you have a record of every important choice you made and why.
  • You document recipes you love. Create an index. Build a personal cookbook.
  • You maintain a reading list with notes on each book. It becomes a searchable library of your learning.

The longer you maintain your markdown knowledge base, the more valuable it becomes. And unlike proprietary apps, which can disappear, your markdown files are yours forever.

Getting Started

  1. Create a knowledge/ folder on your Mac.
  2. Add subfolders for major topics (work, learning, health, etc.).
  3. Write your first note. Use the template above.
  4. Read it back in OpenMark to see it beautifully rendered.
  5. Add a few more notes on things you care about.
  6. After a week, search your knowledge base. Notice how quickly you find things.

That's it. You've started building a knowledge base that's truly yours.

For more on working with markdown, see Using Markdown for Daily Journaling and Why Markdown is the Standard for Software Documentation.

Download OpenMark to read, write, and explore your personal knowledge base with beautiful rendering. $9.99, one-time purchase.