Our minds work in mysterious ways. No matter how hard we try, we cannot always direct our thoughts in an ordered succession of steps, ignoring distractions. It can be equally hard to spot useful links between apparently unrelated pieces of data or to remember all the relevant information connected to a particular issue.

Software programs attempting to make these processes more efficient can take many forms, from desktop or personal "wikis," to "knowledge bases," or "mind mappers." But their general goal is the same: to help users document and connect their ideas as efficiently as possible. This tutorial describes one of these tools, the basic version of Obsidian [1], which runs on Linux and other platforms and is free of charge for personal and educational use.

Main Features

Obsidian, describes itself as a "knowledge base," a "second brain," and a "note multiplexer." It's an Electron application for making notes that makes it easier to catalog, connect, and even publish them. Each Obsidian note is a plain text file, formatted according to the Markdown syntax [2], which is very efficient for formatting text and recording ideas, and so straightforward to use it is almost self-explanatory. In the Obsidian interface, you can view and edit as many notes as your screen and eyesight allow, each in its own pane. Each separate collection of notes (text files) is stored in a "Vault," which is just a normal folder in your filesystem.

To try out Obsidian, I used it for two separate projects. The first, seen Figures 1-7, was created from scratch and includes the initial raw material for an essay on what could be the ideal Linux distribution. The second, discussed later, is visible in Figures 8 and 9 and shows Obsidian handling a full copy of my blog.

A main graph for the "Ideal Distribution project" (Figure 1), shows how the notes are connected to each other visualized as nodes on a graph. The list of all notes that mention the current note, or explicitly link to it (backlinks) is also easily available. For these reasons, some people call Obsidian a Markdown editor with mind-mapping support. Notes can be further organized with tags and other metadata.

Figure 1: An Obsidian Vault graph shows how your different notes are connected to each other.

The first time you start Obsidian, the only existing Vault is the one that contains all the program documentation. To browse its content, click on the question mark button in the lower left corner. Each Vault you create is independent from the other Vaults, meaning that you cannot link notes across Vaults. For the same reason, each Vault gets its own, separate configuration that defines everything from which plugins it can use, to visual settings like background color and graphic theme. All this data is stored in the .obsidian subfolder inside the Vault itself.

The Obsidian documentation says that this "per-Vault" configuration "is useful, for example, if you have one Vault where you keep notes but a different one in which you do long-form writing." That makes a lot of sense, not to mention that fully self-contained Vaults are completely portable from one computer to another. Personally, however, I found it a bit annoying that it seems impossible, from the graphical interface, to import all the customizations already applied to an existing Vault into a new one. The quickest way to do that seems to be to just copy the .obsidian folder from the old Vault to the new one and then restart Obsidian to load those settings.

Obsidian's Openness

In trying out Obsidian, I was most interested in questions that should be the first concern for everyone who understands the importance of open standards and data ownership: Even when all your data remains on your computer, how much of what you do with that program is reusable outside it, and how easy is that to do? Is it possible, for example, to import or generate the initial data for that program automatically with some scripting? Can you edit the data with third-party tools? What about publishing it where and how you want?

With Obsidian, the answers to all these questions were positive, thanks to its "local folders of Markdown files" nature.

Format-wise, besides vanilla Markdown, Obsidian supports constructs for diagrams and math formulas, and the Markdown dialects called CommonMark [3] and GitHub Flavored Markdown (GFM) [4]. There is a plugin called "Markdown Format Importer" that I would not call exactly an importer, but which is useful anyway: it just replaces certain Markdown elements with the ones in the dialects it supports. Obsidian can also directly import notes from Roam Research [5] and zettelkasten-based [6] knowledge-management systems.

You can directly edit Obsidian notes with any text editor, from any platform, in any moment, and even rearrange them in subfolders with a normal file manager. Obsidian will notice the changes and import them automatically, without problems. Coupled with a file synchronization system, this makes it relatively painless to edit the content of a Vault even from smartphones, for which at time of writing there is no Obsidian app. On desktop systems, if you copy and paste text directly from a web page into an Obsidian note, the software will try to automatically convert it to Markdown! Copying the same text with browser plugins like MarkDownload [7] will even add metadata, like source URL and date, to the same note.

On the publishing side, you may export your notes as PDF files or publish them online very easily as one wiki on the Obsidian website through their paid service. However, you may never need any of those options. There are plenty of tools on Linux and any other operating system to convert Markdown files to many other formats and ways to put them online, for example with static website generators like Hugo or Jekyll.

Installation and Configuration

The free version of Obsidian is available for Linux in several package formats. On my Ubuntu desktop, Obsidian was up and running one minute after downloading the Snap package of version 0.11.0 from the website, and installing it with this command:

sudo snap install obsidian_0.11.0_amd64.snap --dangerous

The --dangerous option was necessary, at time of writing, because the package was not registered or digitally signed.

By default, Obsidian comes in two "base" themes, light and dark. The dark mode is the default, but if like me, you find it really hard to read, click on the Settings gear icon in the lower left corner, open the Appearance tab, and switch it to light. Whatever base mode you choose, you can further customize Obsidian by enabling a theme, or even creating your own with CSS rules. Activating the Custom CSS feature allows you to install any of the graphic themes provided by the Obsidian community from the configuration tab. In this tutorial, Figures 1-7 show the Obsidian Solarized theme, and Figures 8 and 9 the default Obsidian look and feel, in the light base mode.

Even before setting the appearance and location of a Vault, you may want to configure how to delete notes, because there are three distinct ways to do it. You can send deleted notes to an Obsidian-only trash folder, send them to the system trash bin, or actually delete them right away.