Joplin Filesystem (JoplinFS)

What is it?

JoplinFS is a (proof-of-concept) wrapper around the Joplin API that allows you to read your Joplin notes as if they were normal markdown files that live on your hard drive. To do this I use the FUSE interface to pass filesystem operations to the Joplin API. Using this enables you to view and interact with your notes as if they they lived on your hard drive instead of a database. If you're familiar with rxliuli's vscode plugin then this concept will be familiar to you. Still doesn't make sense? Take a look at the screenshots below!

Currently this is a read-only implementation, meaning you can view your notes (and notebook structure), but cannot make edits. This isn't a technical limitation with FUSE, I just didn't want to take on the responsibility of keeping notes safe.


Because it seemed fun/cool.

How can I use it?

This is really a demo more than anything. All the code is MIT licensed and available on github but is not meant for wide consumption. I've only tested on Ubuntu 20.04 and have no reason to believe it will work correctly on other systems.

Why though?

A system like this (complete of course) would allow users to use any editing/management paradigm that they like (vscode, sublime text, etc.) while still enjoying the benefits of Joplin for cloud syncing, sharing, mobile etc. It would also play nicely with existing tools that assume documents are stored on a filesystem (backup tools for example). Basically for users that enjoy managing notes on their hardrive this could be a best-of-both-worlds tool.


First we take a look at our ABC folder in Joplin. It's just a mostly empty folder that I set up for this demonstration.

Then we can view the same folder structure from the command line using the tree command. (We can also see the various notes I use for testing Joplin/Joplin plugins).

$ tree test_mnt/
β”œβ”€β”€ ABC_26c8
β”‚   β”œβ”€β”€ And Fun!
β”‚   β”œβ”€β”€ How cool is
β”‚   └── It's easy to
β”œβ”€β”€ Imported Templates - 09082021_1d15
β”‚   β”œβ”€β”€
β”‚   β”œβ”€β”€
β”‚   β”œβ”€β”€
β”‚   β”œβ”€β”€
β”‚   └──
└── test_0707

We don't only have to use the command line, we can also open the notebook from the file explorer!

And notes can be read as if they reside on the hard drive as normal Markdown files!

That's it! I hope you all think this is as cool as I do!


An interesting idea, but I think the following questions are trickier

  1. How are attachment resources handled?
  2. Label setting?
  3. How to reliably sync changes from joplin, event api?
  4. Duplicate Notes or Attached Resources
  1. Attachments are not currently implemented. But they're not so complex. All internal links are handled by creating a "virtual" folder called .links/ that contains all Joplin ids with symlinks to the resource/note/folder that they represent. Then internally, when the user tries to read the file, the contents will be grabbed from the api
  2. Are you talking about tagging items? If so, that will be handled by the .tags/ special folder which contains each tag as a directory that contains symlinks to all the notes with that tag. Once writing is implemented, a new note will be created by creating a symlink in that directory (it's definitely not as convenient as the Joplin app...)
  3. Yes, the event API is used to sync note changes (because that's the only thing actually handled by the events API). Folders and tags will need to be grabbed from the API everytime a user requests them. I don't store the body of any note, and will always grab it fresh from the API, so it's only a matter of keeping track of note names/metadata.
  4. Duplicates are a pain, as you can see in the screenshots I've handled it naively by attaching the first four characters of the ID to the end of every file. It is ugly.

I'd just add the last 4 chars in parenthesis, iff there's a duplicate in the same folder.

1 Like

Great additionβ€”thanks!!

Great idea!
I Can't test at the moment but I think that could have an enormous impact if anyone want to manage their notes in terminal (no need to install Node and Joplin terminal app)

P.S: Fun fact: The english sound "fun-cool" in italian isn't really polite. :smiley:

1 Like