A Guide to Obsidian: Local, Markdown-Powered Networked Notes

April 6, 2021

Obsidian is a note-taking and knowledge management app by the people who created Dynalist, a popular online outliner and one of my favorite tools. They think of it as “an IDE for your notes.” It lets you turn a collection of plain text files into a rich network of linked thought. Get started quickly with this Obsidian notes tutorial.

Obsidian’s data is stored in a local folder of Markdown files. The app’s powerful linking and backlinking features turn these separate files into a knowledge base that operates as your second brain. I was initially underwhelmed with the application until I discovered the extensive functionality that can be added through plugins. You can really make it your own.

Developers use it as a task manager, a software development knowledge base, and as a repository for notes, ideas and code snippets. It’s appreciated for its open architecture, extensibility, code blocks, GitHub integration, Vim key bindings, and configurable hotkeys.

What Is the Obsidian Note-taking App?

The Obsidian program stores its data in folders of Markdown files, so there’s absolutely no lock-in and you can access your notes with any text editor or Markdown editor. An existing Markdown file (or folder of them) can be opened in Obsidian. Your notes are stored locally and can be stored on the cloud using iCloud, Google Drive, GitHub and more.

Obsidian’s About us page lists three fundamental directions the developers are following with the app:

local-first and plain text
link as first-class citizen
make it super extensible

Those values resonate with me. They keep my data secure and under my control, and allow me to decide which features I need and which I don’t. Many of its more advanced features are turned off by default, making it easier to use for less technical users. But there’s a lot of power under the hood.

The application is modal and offers Preview and Edit modes. The first hides the markup and displays images, while the second displays the Markdown syntax and the path to the images. Links are clickable in Preview mode, but in Edit mode you need to Command-click. I guess this makes editing links simpler. You choose which mode is active by default.

Obsidian Mac, Windows & Linux Apps

Electron-based apps are available for macOS, Windows, and Linux. There’s currently no web app, and mobile apps have been out in the wild for a few months now with generally positive reviews from those using them.

Obsidian Main Concepts

Here are some of the main concepts you need to understand to use Obsidian.

Links and backlinks: links transform individual notes into a network of related ideas. Links are created using either Markdown links or [[wikilinks]] according to your choice in the settings. Backlinks are automatically generated and displayed in the sidebar and the context is included. Unlinked mentions are also listed. Follow a link by clicking in Preview mode and Command-clicking in Edit mode, and go back with Command + Option + left arrow.

Backlinks

Aliases: aliases can be created for each note so that you can link to them using different names.

Sidebar: the left sidebar displays backlinks and unlinked references. Unlinked references can be changed into links with a single click. It’s also used by plugins to display an outline of your headings, a tag pane, and more.

Graph view: this is a graphical representation of the relationships between your notes. Hovering over a note shows you all related notes in purple and clicking on a note takes you there.

Graph

Blocks: Each page is made up of blocks which may be paragraphs, lists and more. Each block has an empty line before and after it. You can create links to specific blocks or headings using the syntax [[filename^block]].

Search: search looks for notes containing a word or phrase and displays them in the navigation bar and highlights them in the selected note. Case sensitivity can be turned on and off and operators are available for path, file, tag, line, and section.

Split window: Obsidian allows you to split the window multiple times like in an IDE. Panes can be linked so they scroll together. One use of this is to display the Edit and Preview modes of the same note in two linked panes. Another is to open a link in a new pane.

Markdown: Markdown is supported and displayed in Edit mode but not Preview mode. Like Dynalist and Roam, it’s not quite standard. For example, **bold** text is created with double asterisks and __italics__ requires double underscores rather than single underscores or asterisks. Tables, task lists, strikethrough, and footnotes are supported.

Latex: you can add mathematical notation to Obsidian by enclosing Latex code inside double dollar symbols.

Latex

Code blocks: code blocks are available and syntax highlighting is supported. Prism is used, and 255 languages are supported.

Folding: there’s a setting that allows you to fold headings and/or indents, allowing you to use Obsidian as an outliner. The Outline plugin displays a table of contents of your headings in the sidebar.

Folding

Tags: standard hashtags are supported, as well as nested tags. Multi-word tags aren’t supported. A tag pane can be displayed in the sidebar using a plugin.

Getting Started

Your first step is to download the note-taking app. Obsidian is available for Windows, macOS, and Linux, and a mobile app is available for both iOS and Android. You don’t have to pay or sign up for an account, and by default, your notes are stored locally.

Cost is one of the big advantages Obsidian has over its competitors. It’s completely free for personal use, but there are a number of opportunities to pay:

You can financially support the software by becoming a Catalyst user, which costs from $25 (one-time payment) and gets you a few perks.
Syncing with end-to-end encryption and versioning costs $48/year.
The ability to selectively publish notes costs $96/year.
Commercial users pay $50 per user per year.

The first thing I recommend you do is install the Daily Notes plugin, and you can opt to have your daily note open automatically on startup or open it manually by clicking the icon on the left of the screen.

You can live out of this note, jotting down your thoughts, what you’ve accomplished, and what you plan to achieve. Undone tasks are created with the syntax - [ ] and undone tasks with - [x]. The task list is continued when pressing Enter, and to click the checkbox you need to be in Preview mode. Unfortunately, there’s no view that collates all incomplete tasks.

Rather than storing everything in today’s note, create links to other pages and add the information there. A backlink will be added to today’s page.

If you want easy access to some key notes, turn on the Starred plugin. This allows you to star frequently used notes and searches, and they’ll appear in the navigation bar when you click the star icon at the top of the window.

Also explore the Command Panel plugin (activated by Command + P) which lets you explore common commands and keyboard shortcuts, and the Quick Switcher (Command + O) which allows you to open or create a new note by typing its name.

If you have notes elsewhere, there’s a good chance you can import them alongside the rest of your Obsidian writing. The Help page offers instructions on importing from Roam Research, Notion, Evernote, OneNote, Apple Notes, Bear, Zkn3, and TiddlyWiki.

One of the best ways to get to know Obsidian is via the Demo & Help vault, which is activated by selecting Open Help from the menu. Here you can explore what the app can do while experiencing the interface. At the bottom of the navigation pane, you’ll find a note called Start here. It introduces you to some quick places to dive in, some workflow ideas, and links to the app’s Discord account and forums.

You can also get a feeling for what the Publish feature can achieve by looking at the online version of Obsidian Help.

Extending and Customizing Obsidian

When using Obsidian, don’t just create notes. Take the time to link your notes together and experiment with tags. Choose a few use cases to get started with, such as collecting code snippets, documenting your software, and keeping track of your ideas and inspiration. The more you use the app, the more useful it becomes.

Panes can be dragged and dropped anywhere you like. This lets you set up the software to fit your preferences and workflow. For example, you can have the graph constantly in view in the bottom left, your daily notes open, and another note you’re working on. Once you have a layout you enjoy, save it using the Workspace plugin.

Drag and drop

Obsidian isn’t an outliner. That’s what the developer’s other product, Dynalist, is for. But there’s a number of features you can enable in Obsidian that are quite helpful. In Settings (under Editor) you can individually enable Fold heading and Fold indent. These will allow you to collapse sections of your notes to get an overview of its contents. Enabling the Outline plugin lets you see a clickable table of contents in the sidebar.

The settings also allow you to select dark or light mode and make the window translucent. Text size can be adjusted using Command + + and Command + - as in a browser. In Settings you have access to a range of community themes or you can create your own.

Functionality can be added using core plugins, and there’s also a wide range of community plugins available. These are accessible directly from the “Community plugins” section of Settings where you can install them once you turn off safe mode. The list is quickly approaching 200 in number, and here are a few examples:

Advanced tables
Sliding panes
Mind map
Obsidian Git
Natural language dates
Hotkeys++

If you create your own, you can have it added to the list by creating a pull request to the official obsidian-releases repo. You’ll find instructions on how to do that there, and you’ll also find the API documentation and sample plugin helpful.

The Templates plugin lets you conveniently add snippets of text into the current note. You simply add these to a specific (configurable) folder in Obsidian, and a number of variables are available, including {{title}}, {{date}}, and {{time}}.

Make sure you back up your Obsidian data. You can do this locally with standard backup software or by using a third-party plugin such as obsidian-git. Watch this video for further details and options.

Final Thoughts

Obsidian is a powerful personal knowledge manager and an effective second brain. As you use it, you’ll create and discover connections between your thoughts and ideas.

It’s an excellent alternative to more expensive options such as Roam Research. It’s free for personal use and offers desktop (and soon mobile) apps which Roam currently lacks.

Many users may actually prefer Obsidian’s features over Roam’s. Writers are likely to find Obsidian’s notes easier to work with over Roam’s outlines. In Obsidian, you can take advantage of split windows and customize the layout using drag and drop.

Finally, many users will be attracted by Obsidian’s philosophy and values. The security of locally stored files is appealing, as is the open way your data is stored in folders of plain text files. That’s a stark contrast to what Roam currently offers.

Is Obsidian for you? I’d love to hear your thoughts. The more I use it, the more appealing I find it. It’s been a journey of discovery where I find that functionality I assumed was missing is available as a setting or plugin. That design decision allows users to start with a relatively blank canvas and add the features they need.

Resources:

Text:

Video:

FAQs About Obsidian

What is Obsidian app?

Obsidian is a note-taking and knowledge management app that uses a unique approach called “knowledge graph.” It allows users to create, link, and organize notes in a non-linear and interconnected manner.

How to use Obsidian?

Obsidian provides documentation on its website, including guides, tutorials, and a community forum. Many users also share their personal workflows and tips on platforms like YouTube and blogs, which can be helpful for getting started and exploring advanced features.

Is Obsidian free?

Yes, Obsidian offers a free version with core features. However, there’s also a paid subscription plan called “Obsidian Sync” which provides additional features such as syncing between devices and version history.

What is Obsidian app used for?

Obsidian is used for note taking and knowledge management.

Is Obsidian good for taking notes?

Yes, Obsidian is considered to be a powerful and flexible tool for taking notes, especially for users who prefer a more interconnected and non-linear approach to organizing information.

What is a note in Obsidian?

In Obsidian, a “note” refers to a unit of content or a piece of information that you create within the application. Notes are the building blocks of your knowledge base in Obsidian, and they can contain various types of information, including text, images, links, and more. Each note is represented as a separate file in the file system, and Obsidian’s unique feature is its ability to establish bidirectional links between these notes, creating a network of interconnected information.

What are the cons of Obsidian app?

While Obsidian is a powerful and versatile note-taking app, it’s important to consider its potential drawbacks as well. Among them are a steep learning curve, a lack of collaboration features, and limited export options.

Why is Obsidian better than Evernote?

There are many reasons some users might prefer Obsidian over Evernote, including its non-liniear structure, deep customization, use of local storage, version control, and knowledge mapping.

What programming language does Obsidian use?

Obsidian is primarily built using web technologies, and it uses several programming languages to achieve its functionality, incuding Electron, JavaScript, and CSS. Its notes are written in Markdown, which is worth mentioning because it’s a crucial part of Obsidian’s functionality. Markdown is used for formatting and structuring the content of notes. Obsidian renders Markdown into formatted text, headings, lists, and other elements within the user interface.