Markdown-based knowledge base
Tutorial – Obsidian
Obsidian helps you think and work more effectively by giving you a tool to record, connect, and catalog your ideas and related notes.
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.
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.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
New Steam Client Ups the Ante for Linux
The latest release from Steam has some pretty cool tricks up its sleeve.
-
Gnome OS Transitioning Toward a General-Purpose Distro
If you're looking for the perfectly vanilla take on the Gnome desktop, Gnome OS might be for you.
-
Fedora 41 Released with New Features
If you're a Fedora fan or just looking for a Linux distribution to help you migrate from Windows, Fedora 41 might be just the ticket.
-
AlmaLinux OS Kitten 10 Gives Power Users a Sneak Preview
If you're looking to kick the tires of AlmaLinux's upstream version, the developers have a purrfect solution.
-
Gnome 47.1 Released with a Few Fixes
The latest release of the Gnome desktop is all about fixing a few nagging issues and not about bringing new features into the mix.
-
System76 Unveils an Ampere-Powered Thelio Desktop
If you're looking for a new desktop system for developing autonomous driving and software-defined vehicle solutions. System76 has you covered.
-
VirtualBox 7.1.4 Includes Initial Support for Linux kernel 6.12
The latest version of VirtualBox has arrived and it not only adds initial support for kernel 6.12 but another feature that will make using the virtual machine tool much easier.
-
New Slimbook EVO with Raw AMD Ryzen Power
If you're looking for serious power in a 14" ultrabook that is powered by Linux, Slimbook has just the thing for you.
-
The Gnome Foundation Struggling to Stay Afloat
The foundation behind the Gnome desktop environment is having to go through some serious belt-tightening due to continued financial problems.
-
Thousands of Linux Servers Infected with Stealth Malware Since 2021
Perfctl is capable of remaining undetected, which makes it dangerous and hard to mitigate.