The Origin & Problem
Technical notes, architecture decisions, research ideas, and project documentation often live as collections of Markdown (.md, .mdx) files spread across local folders or headless servers. Over time, these files form rich repositories of knowledge.
However, reading and navigating through them comfortably usually meant one of two compromises:
- Launching a heavy IDE or code editor session just to read formatted text.
- Importing the notes into a centralized note-taking app or database, requiring syncing agents and giving up the raw file hierarchy.
The goal of Markdown Browser was to solve this friction: make browsing existing note directories as pleasant as reading a published book, without introducing intermediate databases or syncing workflows.
The Filesystem-First Philosophy
The core architectural principle is that the filesystem remains the single source of truth. Files stay where they are, in plain text, organized however the author prefers. Any text editor, CLI utility, or Git command can continue modifying them directly.
The web application acts as a non-invasive viewing and navigation lens on top of the filesystem. It scans configured root paths, resolves relative links and images dynamically, and builds rich navigation structures on the fly.
Key Design Decisions
1. Zero-Database Architecture
No SQLite, PostgreSQL, or document store is used. Bypassing a database prevents synchronization drift, eliminates migration overhead, and ensures the tool starts instantly anywhere a folder of Markdown files exists.
2. On-the-Fly Metadata & Structure Extraction
Rather than relying on pre-indexing daemons, the scanner extracts headings, internal relative links, #tags, - [ ] TODO markers, and decisions dynamically. It automatically detects broken local links and builds document backlinks in real time.
3. Minimalist Runtime & Portability
Implemented with Python's standard library HTTP server and Python-Markdown, with zero front-end build pipelines or framework dependencies. Packaged in a compact Docker container that can mount any host directory in read-only mode.
Reading Ergonomics
In addition to standard folder tree navigation, the interface provides multiple contextual viewing modes:
- Folder Map: A high-level bird's-eye view outlining folders, documents, and their internal heading structures simultaneously.
- Metadata Filters: Instant filtering across recent modifications, actionable TODOs, tag clouds, and broken links.
- Refined Typography: Thoughtfully tuned reading typography with light/dark theme toggle and density switching for desktop and mobile screens.