Obsidian Onboarding

Obsidian is a nice application with an uncomfortable on-boarding for new users. It was a struggle for me to remain committed to using the application because the settings are poorly documented and the defaults limit its usefulness. Many of the features I would normally consider “standard” for a Markdown writing tool are actually plugins.

The following setup process gave me a reasonably good editing environment that works on all of my devices.¹ I’m not going to discuss the possible security issues with Obsidian plugins but you might want to research that before using plugins with your private data.

The Basic Setup

Jump into the Obsidian settings before you do anything with the app. I love browsing the settings of new apps but Obsidian settings are so non-obvious that it was hard for me to even get started. I hope this article helps someone.

Setup the following core configurations before moving onto the plugins:

Editor Settings

• Spell Check (Enabled)
• Readable Line Length (Enabled)
• Strict line breaks (Disabled)
• Show frontmatter (Enabled)
• Auto pair brackets (Enabled)
• Auto pair markdown syntax (Enabled)
• Smart indent lists (Enabled)
• Fold heading (Disabled)
• Fold indent (Disabled)
• Default new pane mode: Editor
• Use tabs (Enabled)
• Tab size: 4
• Line wrap (Enabled)
• Auto convert HTML (Enabled)
• Vim key bindings (Disabled)
• Legacy Emacs-style keybindings for macOS (Disabled)

Files and New Link Settings

• Confirm file deletion (Disabled)
• Deleted files: Move to system trash
• Automatically update internal links (Enabled)

The New link format setting is much more critical than it seems. This defines how internal wiki-style links are formatted, which will define how hard it is to move off of Obsidian in the future. I recommend NOT using the Shortest path option because it omits the folder structure in your vault. I like how the Absolute path looks in the link and it’s explicit about where the document is stored. Here’s an example of all three options:

Comments on File Locations

Obsidian has a feature where embedded images and documents are automatically stored within the Obsidian vault. This is really helpful to me because I paste a lot of images into my notes and Obsidian does the right thing and creates an image link automatically. I’ve decided that it’s more safe to store attachments in a subfolder to the current note folder. If I move out of Obsidian I’d like all of the internal references to still work without much fuss.

When I was using only the macOS version of Obsidian, I had deleted documents go to the system trash. But, on iOS this is not ideal because that permanently deletes the file. Now I’ve switched to using the Obsidian trash folder. For some reason Obsidian has decided that this should be a hidden folder, which means that the trash can only be deleted outside of Obsidian using the Finder or Files apps. I’ll just have to remember to manually empty the trash. Weird option.

Plugins

If you stopped here you would not be very impressed with Obsidian. Out of the box it’s not terribly good. Most of the power in Obsidian comes from plugins and CSS snippets.

There are two types of plugins:

Core plugins are provided by the Obsidian developers. They might have more quality control and better support. Or they might not.

Community plugins are found in the wild but many are available in a curated list inside Obsidian. I’d consider these as safe as anything else you find on the internet.

Let’s start by making Obsidian a moderately competitive text editor. Enable the following core plugins in the Obsidian configuration settings:

1. File explorer
2. Search
3. Quick Switcher
4. Tag pane
5. Page preview
6. Starred
7. Command palette
8. Open in default app
9. File recovery

File Explorer

File Explorer seems like something that should not be optional. It provides the sidebar list of files and folders.

Search

This is pretty self explanatory. Obsidian has a quick open

Quick Switcher

This just gives Obsidian the ability to quickly open a document by name by hitting CMD+O. I wish it was more like nvAlt and searched document content too, but it doesn’t and it only searches by document name.

Tag Pane

This plugin elevates tags to a core feature of Obsidian. Tags can be defined with the usual hash syntax (#tag_name) or in the YAML front-matter. The Tag Pane displays a list of all tags in all Obsidian documents. Simple but useful.

Page Preview

What can I say, it let’s you preview your markdown. This is more important in Obsidian than most other editors because Obsidian has some advanced features that are make “preview” more like document processing. You can make Obsidian look beautiful if you try.

Starred

This plugin provides a new quick access sidebar in Obsidian. All starred documents show up in this list. It makes it much easier to find key documents in a collection of hundreds.

Command Palette

This plugin is the heart of Obsidian for me. It is the super power and it should not be a plugin. The command palette is familiar to Sublime Text and VS Code users. Hit CMD+P and it instantly opens to a search box that lists all available commands in Obsidian. This is especially important on macOS because OBSIDIAN HAS NO MENU COMMANDS. I can not believe I am using a macOS app in 2021 that has no menus items, but here I am writing this sentence in that same app.

Open in Default App

Obsidian does not support multiple Windows. It relies on split panes which are inferior for the ways I work. I like to keep multiple reference windows open while I work and do not like to reduce the size of my editing frame. This plugin allows me to open documents in VS Code from within Obsidian. It also helps to open images and PDFs in more appropriate applications.

File Recovery

Thankfully I have not needed to test this plugin. It’s function is right in the name. It also was easy to install and has no noticeable impact on the app performance so I see no reason to turn it off.

Now that we have the core plugins setup let’s add two more community plugins to add a couple more features that I think should be standard. Install the following community plugins:

1. Recent Files
2. Ozan’s Image in Editor

Recent Files

Recent Files adds a new sidebar in Obsidian that shows the list of recently used files.

Image in Editor

Thanks to the multiple people that pointed me to this plugin. Image in Editor displays Markdown images inline while in edit mode. I think this is a huge improvement over toggling between edit and preview mode while I am writing.

Diversion

Obsidian feels like a web-browser for text files to me. It’s an Electron app and all of the plugins are JS and CSS. This is an advantage since there are so many clever web developers that are now applying their skills to a text editor instead of infinite scrolling web articles.

I’d really like to see a more robust marketplace for Obsidian plugins, so that they are sustainable. My fear with Obsidian is that one of the third party plugins I really depend on will go away and then Obsidian is less useful. I don’t think tipping plugin developers is a sustainable business model. I’m sure all of the emacs and vim users are yelling at their screen now.

A Better Obsidian

Here we go. At this point in the setup Obsidian is a pretty good Markdown writing environment that has some fancy tricks for connecting information. But we can do better. There are a few more “Community” plugins that I think makes Obsidian competitive with alternatives. I’m not going to cover niche plugins like Advanced Tables or Calendar plugin but they’ll give you an idea of how far down the rat-hole you can go with this stuff.

Let’s review a few nice bonus features you can install within Obsidian.

1. Starred searches
2. Power search
3. Workbench
4. Templates

Starred Searches

I covered the ”Search” and “Starred” plugins above but you may have noticed I did not mention starred searches. That’s not available out of the box but it can be simulated using the core “Search” plugin mentioned above. With this plugin enabled I can add a tiny code block to a markdown document that executes a query on my Obsidian file collection. Check out the documentation for the plugin to see all of the options, which are extensive. I created a few different documents with embedded searches I often need to do. I starred these documents and can quickly switch to them or load them in a new pane. For example, here’s what one of them looks like:

Power Search

If you have a huge collection of notes and often need more detailed search options, consider the “Vantage search” plugin. It’s a nice way to build up complex searches without memorizing the Obsidian search syntax. You can then generate the embedded search text and add it to the current document.

Workbench

The “Workbench” plugin helps with something I’ve done manually for years. I always keep a scratch file where I can drop bits of text that I will use somewhere else. The Workbench plugin allows me to quickly take a line of text in any active Obsidian document and append it to my scratch file without leaving my current document. Unfortunately, this only works from within Obsidian, which means I can not simply grab a bit of text from a web page and dump it into my scratch file. This is where the Electron-app nature of Obsidian really disappoints me. Fortunately, since Obsidian just uses text files I can solve this with tools like Keyboard Maestro or Shortcuts.

Templates

This is a complicated area of Obsidian because there are several plugins that do similar things. These plugins rely on different syntax but provide a lot of flexibility for quickly creating or inserting text into documents automatically. I’m still deciding which plugin works best for me but there are two that have my attention.

Obsidian has a core plugin for templates and it’s main use is for creating documents from a pre-defined template but it can also insert time stamps. The templates are standard Markdown and they sync just like any other document. I store my templates in a “Meta” directory within my note collection. Here’s the configuration I’m using:

Templater uses a percent tag to distinguish template syntax from standard Markdown. Here’s a simple example that inserts the file creation date:

1<% tp.file.creation_date() %>

Templater is far more than just a snippet system. I’d recommend the excellent summary of Templater by Stephen Millard to understand how deep it can go.

Conclusion

It’s still early days for my fling with Obsidian. It feels like it’s made by people that think like I do. I hope it improves some of the native iOS and macOS features but this initial setup gave me a tool that feels good to work with.