Skip to main content

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

By Adrian Try



Free JavaScript Book!

Write powerful, clean and maintainable JavaScript.

RRP $11.95

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.

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 Obsidian?

Obsidian 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 app. Existing folders of Markdown files 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.

Electron-based apps are available for macOS, Windows, and Linux. There’s currently no web app, and mobile apps are currently in alpha. I’ve only heard positive things from users who are testing 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.


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.


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.


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.


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.


Folders: notes can be organized in hierarchical folders, allowing you to create an outline of documents.

Embeds: notes and other files can be embedded using ![[filename]]. Voice memos can be embedded with the audio recorder plugin.


Vaults: an unlimited number of knowledge bases can be created by using different Vaults. These are simply different folders of Markdown files.

Plugins: extensibility is one of Obsidian’s core values. Currently, 22 plugins are available, including backlinks, graph view, search, tag pane, daily notes, starred notes, templates, and outline.


Getting Started

Your first step is to download the app, which is available for Windows, macOS and Linux. 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 into Obsidian. 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.




Adrian Try is an Aussie writer, musician, cyclist, and tech geek.

New books out now!

Get practical advice to start your career in programming!

Master complex transitions, transformations and animations in CSS!

Latest Remote Jobs