I made notesync, a light weight sync engine for your markdown files that also supports a publishing feature.
There's already a thousand ways to sync your notes, but i decided to make my own because why not :)
It lets you sync your markdown files with images across any number of personal machines and it lets you serve them as a static personal blog!
You can selfhost it on any machine that you own, which is really easily set up with somethine like tailscale to never have your files leave your private network. Or you can selfhost it for as low as ~3$/m on a personal vps provider like hetzner.
You are reading this from my own system hosting this little blog, the time from me writing a note and you seeing the change is sub second!
How it works
Notesync offers two options for sync:
- sync only
- sync + publish
Both work the same way under the hood. You run a server on a VPS (or any machine really) and a client on each device you want to sync from. The client watches your local notes folder for changes using OS-level file events and pushes them to the server over a simple REST API. When you set up a second client on another machine, it pulls everything down on first start and then keeps watching for changes in both directions.
Laptop A (client) ←→ Server ←→ Laptop B (client)
Conflict resolution is dead simple: last write wins, based on file modification timestamps. If you edited a note on your laptop at 3pm and also edited it on your work machine at 4pm, the 4pm version wins. It's not fancy but for personal notes it's honestly all you need.
Deletions are tracked with tombstones — little records that say "this file was deleted at this time". They stick around for 30 days so that when your other client comes online it knows to actually delete the file instead of re-uploading it. After 30 days they get cleaned up automatically.
If you don't want to pull down all your personal notes to for example a work related machine (cough cough Greg Brockman), each client can be configured to be push only. So that only the files created on that machine are synced.
sync + publish
This is where it gets fun. In publish mode your client talks to two servers: your private storage server and a public-facing publish server. Every file gets synced to the private server like normal, but only notes with publish: true in the frontmatter get pushed to the publish server.
---
publish: true
title: My cool blog post
---
The publish server has a built-in site builder that converts your markdown into a static HTML site every time a file changes. Flip publish: true to false and the note gets pulled from the public site on the next sync.
You can sync your files to the same server that you publish to, I just thought that if you are not comfortable to store your notes on a server accessible to the public you are always given the option to store them in a secondary location. Right now I sync my files to a tiny raspberry pi in my closet and then only sync the published notes to my hetzner VPS.
deployment
The whole thing runs in Docker. The install script gives you three choices:
- Blog — server + Caddy reverse proxy with automatic HTTPS
- Storage — just the server, for private sync on something like Tailscale
- Client — just the file watcher, connects to a remote server
A blog setup on a 3€/month Hetzner box gets you automatic TLS, a clean static site, and sync across all your devices. Auth is a shared token, generated on install — nothing to configure beyond that.