An introduction to Joplin, an open source Evernote alternative

Joplin allows you to store and organize notes, files, and more, without fear of vendor lock-in.
984 readers like this
984 readers like this
3 text editor alternatives to Emacs and Vim

opensource.com

Joplin is an open source cross-platform note-taking and to-do application. It can handle a large number of notes, organized into notebooks, and can synchronize them across multiple devices. The notes can be edited in Markdown, either from within the app or with your own text editor, and each application has an option to render Markdown with formatting, images, URLs, and more. Any number of files, such as images and PDFs, can be attached to a note, and notes can also be tagged.

I started developing Joplin when Evernote changed its pricing model and because I wanted my 4,000+ notes to be stored in a more open format, free of any proprietary solution. To that end, I have developed three Joplin applications, all under the MIT License: for desktop (Windows, MacOS, and Linux), for mobile (Android and iOS), and for the terminal (Windows, MacOS, and Linux). All the applications have similar user interfaces and can synchronize with each other. They are based on open standards and technologies including SQLite and JavaScript for the backend, and Terminal Kit (Node.js), Electron, and React Native for the three front ends. 

Joplin is offline-first, so data is always available on the device, even without an internet connection.

Synchronization

One of my goals when creating Joplin was to avoid being tied to any particular company or service for synchronization. As such, its synchronization is designed without any hard dependency to any particular service. Most of the synchronization process is done at an abstract level, and access to external services, such as OneDrive or Dropbox, is done via lightweight drivers. It is easy to support new services by creating simple drivers that provide a filesystem-like interface, i.e. the ability to read, write, delete, and list items.

Switching from one service to another or even to syncing to multiple services at once is possible. Each note, notebook, and tags, as well as the relationships between items, is transmitted in plaintext files during synchronization, which means the data can also easily be moved to a different application, backed up, inspected, etc. This synchronization backend is designed to be durable and future-proof.

Currently, synchronization is possible with OneDrive (by default) or the local file system (which allows synchronizing via a network share). A Dropbox driver will also be available once this React-Native bug is fixed. When syncing with OneDrive, Joplin creates a subdirectory in OneDrive, in /Apps/Joplin, and reads/writes the notes and notebooks from it. The application does not have access to anything outside this directory.

To initiate the synchronization process, follow these steps:

  • Desktop application: Click on the Synchronise button in the sidebar. You will be asked to log into OneDrive to authorize the application (simply input your Microsoft credentials; you do not need to register with OneDrive). After that, the application will synchronize in the background whenever it is running, or you can click on Synchronise to start a manual synchronization.
  • Terminal application: Type :sync. You will be asked to follow a link to authorize the application. After that, the application will synchronize in the background whenever it is running. You can also synchronize outside of the user interface by typing joplin sync from the terminal. This can be used to set up a cron script to synchronize at regular intervals. For example, this would do it every 30 minutes:
    */30 * * * * /path/to/joplin sync
  • Mobile application: Click on the Synchronise button and input your OneDrive credentials.

Attachments

Any kind of file can be attached to a note; in Joplin these are called "resources." In Markdown, links to these files are represented as a simple ID to the resource. In the note viewer, image files will be displayed, and PDFs, text files, or other types of files are displayed as links. Clicking on the link will open the file in the default application.

Importing notes from Evernote

Joplin was designed as a replacement for Evernote, so it can import complete Evernote notebooks, as well as notes, tags, resources (attached files), and note metadata (such as author, geolocation, etc.) via ENEX files. To import Evernote data, first export your Evernote notebooks to ENEX files.

To import your notebooks to Joplin, follow these steps:

  • Desktop application: Open the File menu and click Import Evernote notes, then select your ENEX file. This will open a new screen that will display the import progress. The notes will be imported into a separate, new notebook (this is so, in case of a mistake, the notes are not mixed up with any existing notes). If needed, they can then be moved to a different notebook, the notebook can be renamed, etc.
  • Terminal application: In command-line mode, type import-enex /path/to/file.enex. This will import the notes into a new notebook named after the filename.
  • Mobile application: Currently importing Enex files from the mobile application is not supported. The way to get notes from Evernote into the mobile app is to first import them from the desktop application, and then synchronize with the mobile one.

Comparing the desktop, mobile, and terminal applications

There are differences among the three applications.

Desktop application

Joplin's desktop application

opensource.com

The desktop application is available on Windows, Linux, and MacOS. The main view shows a sidebar with the list of notebooks and tags, the list of notes, and the content of the currently selected note. The main difference in the desktop application is that notes are displayed in a dual view, with the editable Markdown text on one side and the rendered note on the other side. It is possible to display only the note editor, only the view, or both by clicking on the Layout button in the toolbar.

Terminal application

Joplin's terminal app

opensource.com

The terminal application is available on Windows (via WSL), Linux, and MacOS. To install it on Windows or Linux, type:

npm install -g joplin

On macOS it is preferable to use Homebrew, and install the application using:

brew install joplin

If the application does not install due to permission issues, please make sure that your global npm permissions are correct.

To start the application, type joplin. This will open the user interface, which has three main panes: Notebooks, Notes, and the text of the current note. There are also additional panels that can be toggled on and off via shortcuts. To create a new note, type tc. To edit a note, select it and press Enter.

Mobile application

Joplin's mobile app

opensource.com

Joplin's mobile app

opensource.com

The mobile application is available on iOS and Android. Like the other applications, it has a Markdown editor to enter the notes. Once the note has been created, it will display the rendered text with formatting. You can then switch between the editor and the rendered note with the Edit and Back buttons. The notes and notebooks can be synchronized with the desktop or terminal applications.

Interacting with Joplin

Joplin's user interface is partly based on the text editor Vim and offers two different modes to interact with the notes and notebooks:

  • Normal mode allows moving from one pane to another using the Tab and Shift+Tab keys, and selecting/viewing notes using the arrow keys. The text area can be scrolled using the arrow keys, too. Press Enter to edit a note. Various other shortcuts are available.
  • Command-line mode can be started by pressing :. From there, Joplin commands such as mknote or search are available. See the full list of commands.

While you can refer to a note or notebook by title or ID, the simplest way is to use one of these shortcuts to refer to the currently selected item:

Shortcut Description
$n Refers to the currently selected note
$b Refers to the currently selected notebook
$c Refers to the currently selected item, e.g, if the note list is current active, $c will refer to the currently selected note.

Here are some examples:

Create a new note with title "Wednesday's meeting":

mknote "Wednesday's meeting"

Create a new to-do:

mktodo "Buy bread"

Move the currently selected note ($n) to the notebook with title "Personal":

mv $n "Personal"

Rename the currently selected notebook ($b) as "Something":

ren $b "Something"

Attach a local file to the currently selected note ($n):

attach $n /home/laurent/pictures/Vacation12.jpg

The configuration can also be changed from command-line mode. For example, to change the current editor to sublime text:

config editor "subl -w"

Getting help

Complete usage information is available in command-line mode by typing one of these commands:

Command Description
help General help information
help shortcuts Lists the available shortcuts
help [command] Displays information about a particular command

If the help is not fully visible, press Tab multiple times until the console is in focus, and use the arrow keys or Page Up/Page Down to scroll the text.

I'm a software engineer in London. Enthusiastic about open source technologies, I like to contribute to various projects whenever I get a chance. You can find me on GitHub at https://github.com/laurent22

38 Comments

Fantastic work Laurent!

Looks great, would be interested in seeing an AWS S3 sync solution :)

Thanks for your comment. The next sync target will be Nextcloud, and after that I will look at simplifying and documenting the sync driver model (which is already relatively simple since it's often just a wrapper over the native api). That way maybe other users could contribute drivers including S3 and others that have been requested.

In reply to by alastairhm

Looks extremely interesting. Is there a search feature, or did I miss that part?

Yes there is: on the CLI app, type "/" followed by your search query. On mobile and desktop, simply click on the magnifier icon.

In reply to by Vince Flynn (not verified)

Hi,

This sounds like a great idea, and there is certainly a lack of software in this area. Installing from NPM/brew kinda sucks though - why not use repositories, so it is easy to access ? I see a redhat logo at the top of the page ;), and RPMs are easy to write.

I'm also curious as to why electron was chosen - personally, I try to avoid electron/JS software, as my computers and mobile devices are older and don't handle these very speedily.

Hello,

for macOS, Homebrew is a good solution especially since it manages npm packages better than npm itself (default npm settings are quite bad imho and Homebrew fixes this).

On other OSes I agree npm is not the best way to distribute an app as I had lots of issues with it. I've tried writing an APT before (for a different app) but gave up on it as I couldn't get it to work, but I'll look at RPM.

I've initially started the app using Qt and C++, but unfortunately their mobile front end is not great so I dropped the idea eventually. React Native on the other hand, while far from perfect, is much better to get something reasonably good looking without having to do everything from scratch. Then the reason I used this along Electron is that it allows me to write all the backend in JS, and I can then share this with the three apps and support the 5 different OSes. Probably around 80% of the code is shared between apps which is a massive time saver. For example the synchronisation and encryption backends are complex but since they are shared I can focus on making them as robust as possible, and any improvement will automatically benefit all the app.

In reply to by Sam Wan (not verified)

This is extremely interesting! Although for me a killer feature is search including PDF files and pictures OCRed by Evernote. That is a bit hard to replicate without a dedicated server-side component, unfortunately.

Yes OCR would indeed be needed for PDF files. I haven't looked into it yet, I wonder if there's any good open source option? (even server side, in which case users could have an option to self-host it).

In reply to by Lazza (not verified)

Well, Tesseract by Google is pretty neat and it can OCR both pictures and PDF files. I don't know if it can handle rotated text though, which Evernote seems to handle just fine. (Practical example: I had Evernote OCR a picture of a map I took with my smartphone and then I was able to search the street names)

Also, Evernote doesn't just OCR the text but keeps 2 or 3 "most likely" matches for each word, so search is easier because it becomes similar to fuzzy matching.

On an unrelated note, it's a pity I cannot subscribe to comments via email, so I would risk losing track of future responses here. :(

In reply to by Laurent Cozic

I tried downloading the Joplin Windows app from your site and received a virus warning from my Norton scanner referencing WS.Reputation.1 which, subsequently, prevented its installation. Are you aware of this issue?

Also wanted to share the follwing info with you if you're interested in remedying the warning via Norton.

Updated:
February 15, 2012 3:15:47 PM
Type: Other
Risk Impact: High
Systems Affected: Windows

WHITE-LISTING
Software developers who want to accelerate the reputation building process for their new software applications should submit new applications to the Symantec white-listing program. Details of that program can be found here (https://submit.symantec.com/false_positive/).

DISPUTES
If you believe that a program has been incorrectly classified by the Symantec reputation-based security system, then you may submit a dispute using this Web form (URL no longer valid).

Thank you for letting me know. Symantec is being needlessly careful as the app is signed and I think Microsoft has now accepted the app to pass SmartScreen. I've submitted a false positive report to Symantec.

In reply to by John Pugh (not verified)

Symantec has whitelisted the application now. Thanks again for letting me know!

In relation to submission 64146.

Upon further analysis and investigation we have verified your submission and, as such, the detection(s) for the following file(s) will be removed from our products:

File name: Joplin-Setup-0.10.39.exe
MD5: 0176fb217c5073470cbc9df351692cd4
SHA256: 566bd166f812cbe74441eecab9123fd74d77d68b88a4d516b6563f2227c60cd7
Note: Whitelisting may take up to 24 hours to take effect via Live Update

In reply to by John Pugh (not verified)

Looks Amazing! Can't wait to see how this project progresses!

For OCR have a look at Tesseract https://sourceforge.net/projects/tesseract-ocr/

I notice that Markdown newline, by adding to blanks at the end of a line, does not work!? (android version)
GFM tables do work :-)

What about snaps?

I installed the Android app on a tablet, but cannot find the option to sync to a local server. I don't have any MS-Windows systems, so OneDrive is not a workable option even for my tests. I do have several Slackware servers available on my home network, so would prefer to use one of them instead. That would also give me a secure sync option over the VPN I use when on the road.

Has anyone built a Slackware install package or tried the npm2tgz utility yet? All of my workstations also run on Slackware.

The safest option would be a self-hosted server with subdirectories for each user. But setting up my own Nextcloud server is probably overkill. It should be a simple server with an encrypted drive, add end-to-end encryption for the sync with pre-shared master keys to protect it in transit. Then encrypt the data stored on the device/pc and the only gap is what is actually being viewed. Even the aforementioned VPN option for remote users would probably be adequate for many businesses. My last employer used that for all mobile and remote employees. I was able to access my office computer from home on days we were snowed in.

Do you have any documentation for the sync protocol? I am retired now, but I have implemented both Unix daemons and MS-Windows services before.

The question is not whether I am paranoid, it's whether I am paranoid enough.

In reply to by Laurent Cozic

I'm syncing to a folder in my MEGA.nz account. That should take care of end-to-end encryption and versioning. It seems to be working well so far.

I'll comment further when I get the other platforms running -- at this point I've only installed the MacOS version.

You mean you've synced two macOS computer via Mega? That would be quite nice if it works, and yes please let me know if you notice any issue. If it works I'll mention this in the doc since it would be an easy way to support any cloud service without developing specific drivers.

In reply to by Ron Phillips

Well, Windows works, too. I just point whichever Joplin desktop to /whatever/MEGA/joplin, and hit "synchronize." This is going to be very handy! Thank you for this effort!

In reply to by Laurent Cozic

Sorry, it worked when I first started, but now the updates are erratic. I'll try to determine when they do work and when they don't.

Thanks for the update. One reason I can think of is that sync on the filesystem relies on file timestamp (unlike with OneDrive, which provides a delta api to find out what has changed), and there could be issues there if an application changes these timestamps.

In reply to by Ron Phillips

Well, it was worth a try, anyway. I considered storing ENEX files and just importing whenever I open a desktop Joplin, but I didn't see how to export them from Joplin.

Is that in the works?

In reply to by Laurent Cozic

What would you like to export? I don't think there will ever be an option to export to enex, however there will be one to export to Joplin's format (it's already available in the cli tool)

In reply to by Ron Phillips

Great stuff, finally a chance to move away from Evernote!

Nextcloud implementation would be awesome! Waiting for a good alternative for Evernote.

Looks great! I'll give this a try soon as I've been looking for an Evernote replacement for a while. Nextcloud sync would be great, then we can self-host

Thank you for your good work. I only discovered joplin today, but like it already very much!
There are a few features, which I would love see in joplin in the future.
* An iPad app, which makes use of the bigger screen.
* On iOS joplin should enable "open with" so that one could open notes and attachements in other apps. And it should be able to save to the new iOS file manager.
* I would prefer attachments / resources to ceep their file extensions, this way the windows preview could be used to look quickly into them for checking the file content. Especially as one of your goals was not to lock in the users.
* I would love an cryptomator integration. This way one could leave the files and attachments unencrypted on the devices and computer, to be accessible for other software, but synchronize it encrypted into the cloud.
* With enabled encryption on my computer and then the message in the ipad to enter the password, I would have liked a clearer indicator, where to fill in the password. I only saw it the second time.
* Some gui buttons for quick formattting notes, like inserting a big table.
* Entering fotos and text with copy/paste
* An option to resize fotos

But even now Joplin is a greate software and something that was missing before!
Thank You!

Laurent, you are a hero!!

I felt the need of self-hosted notes system after Springpad closed its doors. When I migrated to Evernote, it also became a dying horse. The fear of loosing the notes and favorite application is real in this fast changing world and your steps are mitigating some of it.

Following are few suggestions-

1) Web clipper is very important. If webclipper is not possible, then bookmark based javascript clipper be very helpful for bookmarking.
2) Integration with other services such as wekan (alternative to https://www.kanbanote.com/) can be another useful option.

Thanks again,
AJ

Just gave a try today. Connection with OwnCloud on an external sefvervia WebDAV was a breeze. That's the end of Evernote! Many thanks! You give us freedom!

Awesome work Laurent. I just switched all my notebooks from Evernote. Looking forward to the chrome web plugin to make copying easier.
I was not very happy with Evernote for a year or so now as the search was very slow and almost failed everytime. A note application should make search the best. Only then will it be popular.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.