Notes on Obsidian

I’ve enjoyed using Craft app for the past few months but I’m not thrilled with the incomplete markdown support and the lack of end to end encryption. Like every other nerd, I’ve watched Obsidian rise to the top of new age text editors. This article is my reflection on using Obsidian as a note manager.

Let me start with the baseline. I am using version 0.12.5 of Obsidian on macOS. I prefer the subtlegold theme in dark mode.

I am syncing files through iCloud files. I’m only using one “vault” for my Obsidian files.¹

I also have attachments stored in a sub-folder. This is changed in the Obsidian settings.

I’m using the Obsidian iOS and iPad apps, which are in beta.

I am not using one of Obsidian’s most famous features: backlinks. I don’t like to stray too far from Multimarkdown syntax and I don’t have time to practice a new note system right now. There is generous documentation and tutorials for getting comfortable with backlinks. Baby steps.

TLDR

Obsidian is an incredibly fiddly Electron application that is also very powerful and sticky. The addition of a fully functional iOS app means I can use it full time for text editing. I wish it was more “Mac-like” but I can recommend it for anyone that likes VSCode but wants more focus on text than code.

Plugins

I’m going to start with a discussion of Obsidian plugins because the app is limited without them.

I’m finding two kinds of plugins for Obsidian:

1. Plugins that change the look and function of the standard application
2. Plugins that add new functionality to the application

It’s impressive that there are so many robust and complex plugins for Obsidian. Do you want a calendar based journaling system? There’s a plugin for that. Do you want to extract PDF annotations as notes? There’s a plugin for that. Do you want split panes to stack up instead of sit side by side? Yep, plugin. Tab lover? Enjoy.

The downside to all of this diversity is that there are occasional plugin conflicts and weird application behavior. I had a conflict between two plugins that caused Markdown links to be incorrectly formatted. I’ve also observed some strange UI performance where windows scroll unpredictably when changing focus.

The documentation and quality control of Obsidian plugins is pretty limited. I appreciate that the community plugin browser in Obsidian displays the total number of downloads, but I’d like to see some sort of rating system too. Total number of downloads does not translate into “good” or “bad”.

The Obsidian app without plugins is not very good for me. By installing a few plugins I’ve got what I need but I also have more than I want. I’d like to see better plugin documentation and guides for initial setup. I also think that some of these plugins should be turned on by default.

General Markdown Editing

I love it. Obsidian supports all of the Markdown features I use and it does the right thing almost all of the time. There are some opinionated decisions but nearly everything can be overridden with a different theme or custom CSS.

I’m a little exhausted by the modal Markdown editing vs. display modes. After months with the Craft app I started to appreciate seeing the images inline while I take notes. In Obsidian I need to switch modes to see the images. It’s not terrible but it reminds me that even advanced technologies have anchors in the past.

My main gripe about the syntax in Obsidian is that I don’t really like how footnotes are displayed in a tiny font. There’s no reason for this other than to simulate the limitations of physical typesetting. I’m sure I just haven’t found the right plugin or theme to override this decision.

I also don’t really care for how the header octothorpes are in a smaller font than the main body text. I like to see how many octothorpes I’ve entered because sometimes the font size isn’t obvious.

I installed the Advanced Table plugin which is just a lovely little sweetener for easily making Multimarkdown tables that always look good and behave more like spreadsheets. There are some really nice navigation and filtering tricks with the plugin too.

I really miss Craft app’s embrace of multiple windows. While the Obsidian multi-pane model is “ok” it is far more powerful to have separate windows of a document or reference material open at the same time. I have multiple monitors for a reason. Since Obsidian uses markdown files, I can always open them in another editor like VSCode, but Obsidian can only have one window at a time.

Front Matter and Tags

I’ve used front matter in my notes for years but Obsidian is more pedantic and follows the YAML format. However, it’s worth it for me to switch syntax since Obsidian integrates tags and aliases with the front matter. It doesn’t hurt that Obsidian is using a standard format that I know I can use with other applications. It’s a low-risk change if I want to take advantage of some of the more powerful features of Obsidian.

Obsidian uses the hash-format for tags. That means all of my existing tags using the @ symbol prefix will not work.² Tags can be placed inline with text in Obsidian or in the YAML front matter. Unfortunately the syntax is slightly different. Inline tags use the octothorpe prefix while front-matter tags must exclude the octothorpe.

I’ll have to decide on one system to make sure I’m consistent and don’t lose track of my tags. It’s an odd design choice that I’d like to see fixed.

I do like the optional Tag Pane plugin in Obsidian. It shows the running list and count of tags across the entire note collection. Clicking a tag opens the search interface pre-populated with the tag search.

Images and Attachments

This is an important feature for me. I work with a lot of reference content and very often need to include a diagram or chemical structure in my notes. I do this so often that it has become one of my first tests for any note app. Obsidian passes this test but just barely.

In Craft app, the images embedded in a document are displayed inline and don’t clutter up my list of notes. In Obsidian I’ve configured a separate “attachments” folder where images are stored. The Obsidian syntax is true markdown and doesn’t hide the reference link like Craft app does. Unfortunately Obsidian does hide the image while in edit mode, which is frustrating.

When I write notes, I want to refer back to the images in the note. When using Obsidian I must continually toggle between editing and preview modes to see the images. It’s a common problem with most markdown editors.

The Command and Quick Open Palettes

From years of using Sublime Text and VSCode, I feel right at home with the Obsidian command palette. I like the keyboard-centric navigation of command palettes but I feel that the Obsidian implementation is pretty lazy.

Instead of providing fully functional menus, Obsidian forces users into the command palette plugin, which is optional. This can be frustrating and big barrier to entry. You can ONLY use Obsidian with the command palette, so if that’s hard for you to adopt then Obsidian is not your tool.

I love the command pinning option in Obsidian. I can define which commands I always want to have at the top of the list. I’ve only pinned the template command but I use it a lot and it’s convenient to have at the top of the list.

I don’t really like the Obsidian “Quick Open” palette. It only searches document paths and titles. Craft app is much better at this and not only searches document content but it also shows a small preview of the file or section. Open documents with Obsidian Quick Open requires me to know the exact name of the file I need.

I recommend using the Obsidian search plugin instead of the Quick Open.³ Hit CMD-Shift-F to trigger search and then start typing. Search will show a list of collapsed document views with matches.

The Obsidian search plugin doesn’t have keyboard navigation which is another frustration. It’s a mystery to me why an app without menus has such dodgy command palettes. This is probably my biggest complaint about Obsidian. It’s something that interrupts my writing on an hourly basis. It may also be what stops me from becoming an Obsidian fan.

iOS

This is the elephant in the room and the main reason I ignored Obsidian for so long. There is now a beta version of Obsidian for iOS and it’s good. Many of the rumors I read (or watched on YouTube) were simply wrong. Obsidian for iOS is not just a viewer. In fact, it is a shockingly complete version of Obsidian.

Not only do all of the core functions of Obsidian work on iOS, but many of the plugins and themes sync to iOS. I’m using iCloud Files for syncing Obsidian and it works as well as iCloud sync can work.⁴ It took some time for the initial sync from iOS to Mac but it did eventually work. Since that first rough setup it has worked flawlessly for me.

The iOS apps are still in beta so I’m not going to say too much about their quality. It’s a good start. The iOS apps still feels a bit wonky, like a web app, but it’s functional enough that I’ve been using it to write this article and it feels pretty good.

Since Obsidian is based on folders of markdown files, I feel at easy that if this experiment fails, it’s really easy to move to something else. I don’t have to write an export script or do pretty much anything except move my files to a new directory.

A Few More Plugins

“Templates” are Obsidian’s interpretation of text snippets, which I found confusing at first. Fortunately the core plugin is pretty logical. The Template plugin adds a new command to insert text at the current cursor position. The snippets are stored as markdown files and the file name is used as the snippet name.

There are additional helper plugins that expand on this idea to make snippets very powerful. The best part for me is that all snippets sync to iOS because they are just markdown files. They can be shared on Github as basic markdown. However, the complex templates that integrate with the shell do not work on iOS. I think this will need to change before I put too much work into templates.

The Switcher plugin was pretty confusing. Another example of bad documentation really detracting from a nice feature.

The Admonitions plugin is neat. It uses code blocks to make nicely formatted admonition blocks. I already use a lot of code blocks in my notes for things like, um, code. But I also use it to capture more complex text like JSON or chemical structures. Unfortunately, as with embedded images, these blocks are not rendered until I switch to preview mode. I like that it uses standard markdown but it seems pointless if the nice looking blocks are only revealed in preview mode. Here’s a comparison of how the blocks look in editor and preview modes:

Conclusion

I can see why there are so many vocal fans of Obsidian. It’s a clever app with a lot of nice features. Unfortunately the Electron-ness of Obsidian makes it feel weird on the Mac and iOS. I’ll force myself to stick with it for a couple more weeks. I’ll learn more about it’s quirks and features and hopefully find a nice middle ground with it. At least my notes aren’t stuck in a database or dependent on a developer’s idea of good Markdown export. It’s a safe experiment. More importantly, I love trying new tools and experimenting with new systems, even if I don’t fully embrace them.

---

1. Here’s the point where security wonks yell at the screen to say that iCloud is not encrypted end to end. I know that. I also trust Apple more than a VC-funded startup to be responsible with my data over the long haul. ↩︎

2. I realize that Twitter has eaten the world and we must all use the hash tag. I’ve resisted this since my tags pre-dated Twitter. ↩︎

3. Honestly, I am baffled that search requires a plugin. This is a very strange choice to me. ↩︎

4. As always, when iCloud sync isn’t working there is no way to troubleshoot. There’s no feedback whatsoever. During my setup I could see that there was a new folder created in iCloud drive from the iOS side but that same folder did not appear on my Mac. The fix was to ignore it and it eventually showed up. ↩︎