flatnotes

Flatnotes is a self-hosted note-taking web application built around a single design principle: your notes are yours. Every note is stored as a plain Markdown file in a flat directory — no database, no proprietary format, no complicated folder hierarchy. You can move, edit, or delete those files with any tool at any time, even while Flatnotes is running, and it will pick up the changes automatically on the next search.

The interface is intentionally minimal. There are no notebooks, no hierarchies, and no organizational overhead. Instead, Flatnotes relies on powerful full-text search powered by Whoosh, inline tagging with #hashtag syntax, and wikilinks ([[Note Title]]) to let you navigate your knowledge base naturally. A keyboard shortcut — just press / — brings up search from anywhere in the app.

Behind the minimal UI sits a capable FastAPI backend with a documented REST API, optional JWT-based authentication with TOTP two-factor support, a mobile-responsive Vue 3 frontend, and a Docker image that makes self-hosting straightforward. The entire system deploys in minutes and requires nothing beyond a mounted volume for your note files.

Flatnotes is designed to stay lightweight and focused. The maintainer deliberately limits new features to preserve the distraction-free experience, making it a stable, predictable tool for anyone who wants a personal knowledge base without the operational overhead of a full database-backed CMS.

What You Get

• Flat Markdown file storage — Each note is a plain .md file in a single directory; no database, no proprietary format, and external edits are picked up automatically on the next search without restarting the app.
• Incremental full-text search — Whoosh powers a server-side search index with stemming, accent folding, tag field boosting, and date parsing; press / from anywhere in the app to open search instantly.
• Wikilink navigation — Link between notes using [[Note Title]] syntax; tags written as #hashtag are automatically hyperlinked to a search for other notes sharing that tag.
• Dual-mode Markdown editor — Toggle between raw Markdown and a visual WYSIWYG mode backed by TOAST UI Editor, with code syntax highlighting and live preview.
• Flexible authentication — Choose at deploy time from no auth, read-only public access, username/password with JWT sessions, or full TOTP two-factor authentication via a single environment variable.
• RESTful API — A fully documented HTTP API (served at /docs) lets you programmatically create, read, update, and delete notes and attachments for automation and third-party integration.
• Customisable home page — Configure a quick-access section on the home screen to display recently modified notes or the results of a custom search query on load.
• Attachment support — Upload and serve binary attachments alongside notes via dedicated API endpoints, with relative URLs that work outside the Flatnotes context.

Common Use Cases

• Personal knowledge base — A developer stores technical notes, code snippets, and research summaries as Markdown files, using wikilinks to connect related topics and full-text search to surface anything within seconds.
• Private team wiki — A small DevOps team mounts a shared volume and runs Flatnotes with password authentication to maintain a searchable runbook of deployment procedures and incident notes.
• Daily journaling — A writer keeps dated journal entries as individual Markdown files, using the #hashtag tagging system and date-aware search to review entries by topic or period.
• Git-backed note sync — A user commits their Flatnotes folder to a private Git repository, editing notes on any device through their preferred text editor, and using Flatnotes as a unified browsing and search interface.
• Homelab documentation — A self-hoster documents their server configuration, credentials, and maintenance history in Flatnotes, hosted on the same machine as their other services via Docker Compose.
• Read-only knowledge portal — A user configures Flatnotes in read-only mode to publish a curated set of Markdown notes as a lightweight internal wiki, shareable without exposing edit capabilities.

Under The Hood

Architecture Flatnotes follows a clean layered design: a FastAPI Python backend serves a compiled Vue.js SPA, with abstract base classes defining interfaces for notes, authentication, and attachments. Concrete file-system implementations are plugged in at startup via a central GlobalConfig factory, producing a strategy pattern where the storage and auth backends are interchangeable without touching route handlers. API routes are deliberately thin, delegating all business logic to injected service instances, which maintains a consistent single-responsibility boundary. The Vue frontend uses Pinia for global state and Vue Router for client-side navigation, organized into views and reusable components. Environment-driven configuration via a get_env() helper keeps operational concerns isolated from application logic, and the Docker multi-stage build separates frontend compilation from the runtime image cleanly.

Tech Stack Vue 3 with the Composition API, Pinia store, and Vue Router form the SPA frontend, compiled with Vite and styled with Tailwind CSS 3 and SCSS. TOAST UI Editor provides dual raw-Markdown and WYSIWYG editing modes with code syntax highlighting. The backend runs on FastAPI with Pydantic models for request validation and structured response types. Whoosh, a pure-Python full-text search library, maintains an incremental search index stored alongside notes in a hidden .flatnotes subdirectory. Authentication uses python-jose for JWT tokens and pyotp for optional TOTP two-factor authentication. PrimeVue supplies UI primitives such as toast notifications and contextual menus, while MDI icons via @mdi/js provide a lightweight SVG icon set. The entire stack ships in a Docker container using a multi-stage build with Node.js for frontend compilation and Python 3.11-slim for the runtime.

Code Quality No automated test files exist in the repository — the package.json test script explicitly exits with an error, and no Python test suite is present. The backend compensates partially through explicit exception handling: API route handlers catch specific Python exceptions such as ValueError, FileNotFoundError, and FileExistsError and map them to appropriate HTTP status codes rather than letting errors propagate silently. Pydantic models enforce input validation at the API boundary. The Vue frontend is plain JavaScript without TypeScript, limiting static safety. Python formatting is governed by isort with a Black profile and Prettier handles the frontend, providing consistent style. The codebase is readable and modestly commented, with docstrings on public methods, but the absence of any test coverage means regressions can only be caught manually.

What Makes It Unique Flatnotes occupies a deliberate niche: it provides search and navigation capabilities typically associated with database-backed note apps while maintaining pure flat-file storage with no lock-in. The Whoosh search index is incremental and detects external file modifications between searches without requiring a restart, which means your preferred desktop editor and Flatnotes coexist transparently on the same folder. The combined wikilink resolution, inline tag extraction (tags are stripped from search content but boosted as a separate indexed field), and human-readable URL routing via note titles rather than opaque IDs create a cohesive navigation experience. Authentication complexity scales from zero to TOTP two-factor authentication through a single FLATNOTES_AUTH_TYPE environment variable, with no admin UI required — an unusually ergonomic self-hosting configuration surface.

Self-Hosting

Flatnotes is released under the MIT License, one of the most permissive open-source licenses available. You are free to use it commercially, modify the source code, distribute it, and incorporate it into proprietary products without any copyleft obligations. The only requirements are that you retain the copyright notice and license text. There are no dual-licensing restrictions, no commercial use clauses, and no CLA to sign.

Running Flatnotes yourself requires a Docker-capable host and a persistent volume for the notes directory. The application is stateless except for the note files and the Whoosh search index stored alongside them, which makes backup straightforward: just back up the mounted data directory. Updates require pulling a new Docker image and restarting the container; the search index rebuilds automatically if the schema version changes. There is no external database to manage, no background worker queue, and no cache service. For a single-user or small-team deployment, a low-resource VPS or a home server handles it comfortably. Scaling to multiple concurrent users is constrained by single-process Python and file-system locking on the index, so it is best suited to personal or small-team use rather than large organisations.

There is no managed cloud offering or paid tier for Flatnotes. The project does have a PikaPods partnership that lets you launch a hosted instance with one click — PikaPods handles infrastructure, updates, and backups for a usage-based fee — but this is a third-party service, not an official product. Outside of PikaPods, you are fully responsible for uptime, upgrades, backups, and security hardening. There is no commercial support contract, no SLA, and no enterprise feature tier. The maintainer accepts feature requests and bug reports via GitHub Issues, but pull requests are currently disabled by policy — the project is intentionally kept minimal and tightly scoped by a solo maintainer.