files.md: A Local-First Markdown App with a Go Sync Server

What files.md Is and the Problem It Addresses

files.md is a web application that saves your notes directly as .md files in a local folder on your device. The README lists the use cases: notes, documents, project files, journals, habits, checklists, and tasks. All of these land in plain Markdown files that you can open with any text editor, version control with git, or move between machines by copying files.

The core design position is that your data should not leave your device by default. Unlike services that store notes in a proprietary database or sync them to a vendor's cloud automatically, files.md uses the browser's File System API to read and write files in a folder you designate on your local disk. No account is required to start using it.

The author is clear about who the project is not for: the README includes a substantial philosophical section arguing that elaborate Personal Knowledge Management systems often produce the illusion of understanding without the actual work of thinking. The application is intentionally limited. Features that do not serve direct note-taking are absent rather than deferred.

Local-First Storage and PWA Installation

files.md runs entirely in the browser and uses the File System API to persist changes to a local folder. The README notes that Chromium-based browsers (Chrome, Brave) have the best File System API support at the time of writing. The API is required for the app to save changes directly to disk; without it, notes can be captured but not persisted to a local folder automatically.

Installing the app as a PWA makes it behave like a native application. The README describes clicking the install button in the Chromium address bar on the right side to add it to the system. Once installed, the app works offline.

To get updates after installation, the README instructs users to force-refresh with Cmd+Shift+R, since the browser caches the app assets aggressively. This is a trade-off of the offline-first design: updates do not install automatically in the background.

The hosted version is available at app.files.md, which is described as a Beta. No login or signup is needed to use it; the browser instance connects to your local file system directly, not to any server at that domain.

Self-Hosting with the Go Server and Docker

The Go server in this repository provides synchronisation across devices. It is a single binary compiled from cmd/server. The Dockerfile uses a two-stage build: a Go 1.24 Alpine build stage produces the binary, and a minimal Alpine runtime image runs it.

Build and run with Docker using the Makefile targets:

make docker_build

Or start with Docker Compose, which the Makefile documents as the compose_up target:

make compose_up

The compose.yaml maps port 80 on the host to port 8080 inside the container and mounts two named volumes: storage for the .md files and tokens for authentication tokens. The environment variables APP_URL, STORAGE_DIR, and TOKENS_DIR configure the server's behaviour. CERT_DIR is left empty by default; providing a certificate directory enables HTTPS.

For local development, the server can be run directly:

go run ./cmd/server

The README also mentions iCloud, Dropbox, and Google Drive as alternatives to the built-in sync server. Since files are stored as plain files on disk, any sync service that mirrors a local folder works without any server deployment at all. The Go server is needed only when those services are not available or not preferred.

The Chat Interface and Telegram Bot

The main mechanism for quick note capture is a chat-like input accessible with Cmd+Enter. The user types a thought and sends it; the app prompts for a destination file or lets the user choose later. This flow is designed to not interrupt reading or thinking: the README describes using it to capture one idea per note while reading a book without stopping to organise.

The same flow synchronises with the Telegram bot, available at https://t.me/FilesMDBot. Notes sent to the bot are saved to the same .md files as the web interface. The README lists the bot's functionality as supporting the full feature set for note creation and retrieval, covering the common case of capturing something on a phone and having it appear in the web interface on a desktop.

The cron job dependency (github.com/robfig/cron/v3) visible in go.mod suggests the server runs scheduled tasks, likely for syncing notes between the bot and storage.

The Deliberate Scope: One Idea Per File, No Templates

The README presents a specific working method that the application is designed around. Each note should contain one idea and be understandable without external context. Notes are linked using the [ character to trigger linking. The author describes spending five years building this practice alongside the software.

The README includes a quote from an external article about Obsidian that describes how elaborate PKM systems can become a trap: deferring the actual work of thinking to an increasingly complex system that grows without producing insight. This quote positions files.md as a deliberate counter-design. The application removes most of the features that enable that kind of system-building.

This is not a bug or a gap in development. The README states directly that only necessary features are included and that restrictions foster creativity. There is no graph view, no backlinks panel, no tag system, no plugin architecture, and no block-level database. The codebase is described as simple enough for one person or an LLM to hold in their head, and that constraint shapes what the application does and does not do.

Limitations: Browser Dependency, Beta Status, and Narrow Scope

The File System API requirement means files.md works reliably only in Chromium-based browsers. The README notes this explicitly, flagging Chrome and Brave as having the best support. Firefox users face reduced functionality. Safari's File System API support is incomplete enough that the README does not list it as supported.

The hosted version at app.files.md is described as Beta. No GitHub releases have been published. The go.mod file pins go 1.24, but the release cadence and the stability of the sync API between client and server are not documented in the README.

The Telegram bot is the only supported mobile access path. There is no native mobile app. The chat-based interface works for quick capture but does not offer a full note-browsing experience on a phone screen.

The server has no built-in user management. The tokens mechanism visible in the compose.yaml handles authentication, but multi-user deployments are not documented. The README's framing is consistently single-user: one person's private workspace.

files.md vs Obsidian: Scope vs. Flexibility

Obsidian is a local-first Markdown editor with a plugin ecosystem, graph view, backlinks, tags, and a community of third-party extensions. It runs as an Electron application on the desktop and as a mobile app on iOS and Android. Its core is free; sync and publish are paid optional services.

files.md covers a much smaller surface area deliberately. It has no plugin system, no graph view, and no desktop or mobile app. What it offers that Obsidian does not is a built-in sync server shipped as a single Go binary and a Telegram bot for mobile capture.

The README quotes an article describing how Obsidian's power can become a liability: the system grows, organisation becomes the activity rather than thinking, and the complexity becomes its own maintenance burden. Whether that description reflects a user's actual experience depends entirely on how they use the tool. files.md removes the option of building that kind of system by design.

For a developer who wants to self-host sync without a third-party service, or who specifically wants to avoid an Electron app, files.md provides both. For someone who needs rich formatting, embedded databases, or an established plugin ecosystem, Obsidian is the more capable choice.

Editorial conclusion

files.md is well-matched to someone who wants their notes in plain .md files they own, does not want to install an Electron app or run a cloud service, and is comfortable working primarily in a Chromium browser. The offline-first design and single-binary server make it practical on a home network. Someone who needs rich formatting, embedded databases, or mobile apps beyond a Telegram bot will find the scope too narrow. Before deploying the server, set the APP_URL environment variable correctly and decide whether iCloud, Dropbox, or the built-in sync API fits better for your sync setup.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. zakirullin/files.md on GitHub