flatnotes is a self-hosted, database-less note-taking web app that keeps every note as a Markdown file in a flat folder, built for individuals and small teams who want a browser-based editor without handing ownership of their notes to a hosted service.

What it is

flatnotes is an open-source note-taking application written in Vue and licensed under MIT, distributed primarily as a Docker image. It presents a mobile responsive web interface for writing and searching notes, and it stores those notes as plain Markdown files in a single flat folder. There is no database. The full-text search index is built with Whoosh, a pure Python search engine library, and the in-browser editing experience comes from TOAST UI Editor, which provides GitHub Flavored Markdown and WYSIWYG modes.

The concrete problem it solves is note lock-in. Database-backed and proprietary note applications hold content in stores that require exports and migrations, and they impose their own formatting and folder structures. flatnotes replaces that store with the filesystem: your notes are just markdown files, with no proprietary formatting and no complicated folder structure. The only thing flatnotes caches is the search index, and that is incrementally synced on every search and when flatnotes first starts. Because of that, markdown files can be added, edited, and deleted outside flatnotes even while it is running, and the files can be moved elsewhere to another app at any point.

Key capabilities

• Raw and WYSIWYG markdown editor modes, provided by TOAST UI Editor.
• Wikilink support for linking between notes, written as [[My Other Note]].
• Note tagging alongside advanced search functionality, with full-text search reachable from anywhere in the app using the / keyboard shortcut.
• Multiple authentication options: none, read-only, username/password, and 2FA.
• A RESTful API, with details published in the project wiki.
• Customisable home page, light and dark themes, and a mobile responsive interface.
• A deliberately distraction-free design with no folders or notebooks: all notes sit in a flat list backed by search and tagging.

Who uses it and how

• Self-hosters running the container dullage/flatnotes:latest with a data volume such as ./data:/data, optionally splitting out the search index with ./index:/data/.flatnotes.
• People who write or edit notes with other tools, since markdown files stay editable outside flatnotes while it runs and the search index re-syncs.
• Deployments that need to expose a note collection to readers without granting write access, using the read-only authentication type.
• Private or shared deployments that require access control, configured through FLATNOTES_AUTH_TYPE with username/password or 2FA.
• Users who would rather not operate Docker at all, using the PikaPods hosted option.

Getting started

The recommended self-hosted route is Docker, either a docker run of dullage/flatnotes:latest or an equivalent compose file configuring PUID, PGID, FLATNOTES_AUTH_TYPE, FLATNOTES_USERNAME, FLATNOTES_PASSWORD, FLATNOTES_SECRET_KEY, and port 8080. A hosted alternative is PikaPods, which resets its demo site every 15 minutes.

How it compares

The facts list no paid products that flatnotes replaces and name no directly comparable note-taking tools; the two credited projects, Whoosh and TOAST UI Editor, are dependencies rather than rivals. On this registry page it stands alone.

When to use it — and when not to

A self-hoster must run a container with a persistent volume and set configuration including FLATNOTES_SECRET_KEY and the chosen authentication credentials, but there is no database to run, back up, or migrate, which is the entire point. Skip it if nested folders or notebooks are required, because the design intentionally omits hierarchy and the roadmap explicitly limits new features to keep the app simple and distraction-free. It is also a poor fit for anyone who wants a hands-off managed service with no container to operate; the repository last received a push on 2026-08-29 and carries 124 open issues.

docker run -d \
  -e "PUID=1000" \
  -e "PGID=1000" \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e 'FLATNOTES_PASSWORD=changeMe!' \
  -e "FLATNOTES_SECRET_KEY=aLongRandomSeriesOfCharacters" \
  -v "$(pwd)/data:/data" \
  -p "8080:8080" \
  dullage/flatnotes:latest

version: "3"

services:
  flatnotes:
    container_name: flatnotes
    image: dullage/flatnotes:latest
    environment:
      PUID: 1000
      PGID: 1000
      FLATNOTES_AUTH_TYPE: "password"
      FLATNOTES_USERNAME: "user"
      FLATNOTES_PASSWORD: "changeMe!"
      FLATNOTES_SECRET_KEY: "aLongRandomSeriesOfCharacters"
    volumes:
      - "./data:/data"
      # Optional. Allows you to save the search index in a different location: 
      # - "./index:/data/.flatnotes"
    ports:
      - "8080:8080"
    restart: unless-stopped