The index.md Pattern: Make Your Wiki Navigable in 30 Seconds

You have 347 markdown files. They're all perfectly formatted. Your folder structure is immaculate. And you cannot find anything.

This is the curse of the well-organized knowledge base. It looks great in a tree view, but when you need that note about PostgreSQL connection pooling, you spend eight minutes clicking through folders. By the time you find it, you've forgotten why you needed it.

The index.md pattern solves this with one rule: every directory gets an index.md that lists what's inside. That's it. No complex tooling, no graph databases, just a markdown file that acts as a table of contents.

Analogy: Think of index.md like the directory at the mall entrance. You don't need to walk every hallway to know where the food court is. You look at the map, see "Food Court: Level 3, West Wing," and go directly there.

Table of Contents

1. Why Most Note Systems Fail the Find Test
2. The Index.md Convention Explained
3. Real Template You Can Copy Today
4. Project vs Reference Split
5. How LLMs Read Index.md First
6. The 30 Second Update Rule

Why Most Note Systems Fail the Find Test

Most developer wikis fail because they optimize for writing, not reading. The folder structure makes sense when you create the note. Six months later, you have no idea if that AWS lambda debugging guide is in /backend/deployment/ or /cloud/aws/serverless/.

The find test is simple: can you locate a specific note in under 10 seconds without using search? If not, your system is broken.

Three common failure modes:

Search helps, but only if you remember keywords. When you search for "docker" and get 43 results, you're back to clicking through files. Index.md gives you curated navigation with context.

The Index.md Convention Explained

Every directory gets an index.md file. That file lists:

1. What this directory contains
2. Links to subdirectories and their index.md files
3. Links to individual notes with one line descriptions
4. When to use this section vs others

The convention is simple:

• Root directory has /index.md (your wiki home page)
• Every subdirectory has subdirectory/index.md
• Index files link to other index files and individual notes
• Descriptions are short, 5-15 words max

This creates a navigable hierarchy. You start at the root, see the major sections, click into the relevant one, and find your note in two or three clicks.

Real Template You Can Copy Today

Here's a working template for a root index.md:

# Wiki Home

Last updated: 2024-01-15

## Quick Links

- [Projects](projects/index.md) - Active work, sprint notes, implementation details
- [References](references/index.md) - Documentation, how-to guides, troubleshooting
- [Archive](archive/index.md) - Completed projects, deprecated notes

## Projects

- [API Redesign](projects/api-redesign/index.md) - REST to GraphQL migration (2024 Q1)
- [Database Migration](projects/db-migration/index.md) - Postgres 14 to 16 upgrade notes

## References

### Backend
- [PostgreSQL Tips](references/backend/postgres-tips.md) - Connection pooling, indexing strategies
- [Redis Patterns](references/backend/redis-patterns.md) - Caching and session management

### DevOps  
- [Docker Compose](references/devops/docker-compose.md) - Local development environment setup
- [GitHub Actions](references/devops/github-actions.md) - CI/CD pipeline configuration

## Recent Additions

- 2024-01-15: Added Kubernetes troubleshooting guide
- 2024-01-10: Updated API authentication flow diagram
- 2024-01-08: Archived 2023 Q4 sprint retrospectives

For a subdirectory like references/backend/index.md:

# Backend References

[← Back to Wiki Home](../../index.md)

## Database

- [PostgreSQL Tips](postgres-tips.md) - Connection pooling, query optimization
- [MongoDB Patterns](mongodb-patterns.md) - Schema design for document stores
- [Migration Scripts](migration-scripts.md) - Safe schema changes in production

## API Design

- [REST Best Practices](rest-practices.md) - Versioning, error handling, pagination
- [GraphQL Resolvers](graphql-resolvers.md) - N+1 query prevention

Notice the breadcrumb link back to the parent. This makes navigation bidirectional.

Project vs Reference Split

The most useful organizational split is project versus reference:

Projects are time-bound and specific:

• Sprint planning notes
• Architecture decision records for a feature
• Implementation details that become stale after launch

References are timeless and reusable:

• How-to guides
• Troubleshooting checklists
• Configuration templates
• Best practices

When a project finishes, its tactical notes go to archive. The reusable patterns get extracted into reference docs. This keeps your active wiki lean.

Example flow:

Project note lifecycle with index.md at each stage

How LLMs Read Index.md First

Tools like Claude Code or Cursor look for index.md when you ask about your codebase. When you prompt "Where's the authentication logic?", the LLM checks the root index.md first, sees the references section, follows the link to references/backend/index.md, and finds the auth documentation.

This matters because LLMs have context windows. They can't read 347 files. But they can read a few index files and navigate to the right note.

Andrei Karpathy's wiki pattern uses this explicitly. His instruction to Claude:

"When I ask about a topic, check wiki/index.md first. If there's a relevant page, read it and answer from that. If not, research the topic, write wiki/new-topic.md, and update index.md."

The LLM maintains your wiki by following the index pattern. It never creates orphan files. Every new note gets linked from an index.

The 30 Second Update Rule

The pattern only works if you update index.md when you add notes. Make it a habit:

1. Create a new note
2. Open the relevant index.md
3. Add one line with a link and short description
4. Save

This takes 30 seconds. If you skip it, the note becomes invisible. You'll forget it exists in two weeks.

Some developers automate this with a script that scans for new .md files and adds them to index.md with a TODO description. Then you just fill in the description manually.

Example script logic:

find . -name '*.md' -newer index.md -not -name 'index.md' | while read file; do
  echo "- [$file]($file) - TODO: add description" >> index.md
done

This ensures nothing gets lost even if you forget the manual update.

Conclusion

The index.md pattern is brutally simple. One file per directory that lists what's inside. No special tools, no plugins, just markdown files and links.

It works because it matches how you actually search for information. You start broad (which section?), narrow down (which subsection?), and land on the specific note. Three clicks instead of thirty.

Create your root index.md today. List your main sections. Add descriptions to five important notes. That's it. You've made your wiki navigable.

The test: close your editor, wait five minutes, and try to find a specific note using only index.md links. If you can, the pattern is working. If not, your descriptions need more context or your sections need better names.

Start with the template above. Adjust it for your structure. Update it for 30 seconds every time you add a note. Your future self will thank you when they find that PostgreSQL tip in eight seconds instead of eight minutes.