|||

Why and how to use Obsidian and NotePlan together

⚠️ Oct 30, 2020 — CloudKit sync users: The latest edition of the NotePlan 3 beta moves the directory of your NotePlan notes to comply with Apple’s sandboxing policies. The new location is ~/Library/Containers/co.noteplan.NotePlan3/Data/Library/Application Support/co.noteplan.NotePlan3/. If you’d implemented this guide before Oct. 30, 2020, you’ll want to open a “new” Obsidian vault at this location (and reset any other scripts/apps that were interacting with NotePlan notes synced via CloudKit.) ⚠️

Note: both Obsidian and NotePlan 3 are beta apps. Beware! Much can change, and you should expect glitches. Always make backups.

In this post, I provide an overly-detailed overview of setting up and using Obsidian and NotePlan together. Most of this is intuitive, but it may be useful to have it all in one place.

Obsidian is a linked thought app that operates on markdown files.1 It’s a sleek, highly community-driven tool—in fact, an alpha of Obsidian’s API was just launched. Obsidian provides a kind of Integrated Development Environment (IDE) for thinking. It has lots of neat plugins, a graph view to show the connections between your thoughts, and extensive customizability.

A screenshot of Obsidian with this article in view.

NotePlan is a calendar-driven note-taking app for Mac, iPhone, and iPad.2 It is a clean and effective way of linking notes with Calendar and Reminders apps. NotePlan is a kind of super-powerful “bullet journal.” It allows you to take extensive, linked notes about your life and work, and it provides intuitive ways of searching and filtering those notes for review and actionability while allowing you to link them with events, reminders, and time blocking. And, as of the current beta of NotePlan 3, it works on markdown files, too.

A screenshot of NotePlan with this article in view.

To state this clearly: you can use Obsidian and NotePlan to work with the exact same files—no import-export-import roundabout nor sync processes needed. Both Obsidian and NotePlan recognize and navigate the same [[wikilink]]-style note links.3

Why use NotePlan and Obsidian together?

Obsidian and NotePlan provide a complementary set of tools.

Obsidian’s based on Electron, and as a result it’s highly flexible and has an extensive cross-platform community building new ways of working with your notes. However, it only operates on desktop operating systems at the moment (e.g., macOS). Also, for anyone who’s used to working on a Mac, you may find that Obsidian misses out on a lot of the Mac’s native power tools. You can’t use e.g., services or AppleScript to work with it, and it lacks a lot of menu options and default macOS text tools (like text replacement and default text navigation shortcuts). And because there’s no iOS companion, you may be frustrated by the inability to access your thinking when you’re away from the desk.

NotePlan is more focused. It can’t show you a local graph visualization of how your current note relates to the rest of your thinking, render your notes as presentation slides, or run RegEx searches on your notes (all things Obsidian can do!). But it is built for Apple technologies. It has great URL scheme support, works with all the macOS features you know and love. It runs beautifully on iPhone and iPad. You can sync your notes with fast and reliable CloudKit syncing. And on iOS/iPadOS, with Shortcuts and NotePlan’s URL scheme, you can build all kinds of neat workflows to speed up adding or retrieving thoughts from your notes database.4

Either app on its own might be good enough for many people. Below I go over some of the reasons you might want both.

What does NotePlan bring to Obsidian?

iPhone/iPad note editing and access. NotePlan gives us a powerful way to access and add to our notes when away from the desk.

Task filtering. If you’re not managing projects/tasks within your notes, this won’t matter. But if you are, NotePlan provides an intuitive rollup of tasks that is very handy. (E.g., I can review and interact with every “overdue” task from my previous daily notes in one view.)

NotePlan also provides a few other benefits unavailable in Obsidian. For example, you can open notes in their own windows on macOS; you can use @ to tag people and it’ll pull them together, and there’s a CloudKit-based collaboration option (e.g., share a note with another NotePlan user and you can both edit it simultaneously).

What does Obsidian bring to NotePlan?

I find Obsidian’s “IDE for thought” approach to be more productive than NotePlan. The graph, embeds, search tools, command palette, and pane management features all make Obsidian a bit more powerful, for me. Plus, customizability (especially with plugins) is a major boon—I love using the “focus mode” and “Andy’s mode” tweaks to get different emphases on what I’m working on, for instance.

As both apps continue to develop, I think we’ll see more divergence than convergence here.

(In the screenshot immediately below, the left window shows Obsidian’s view of my Workflows ⨳ note, including some graph and backlinking metadata. The right shows a NotePlan-filtered task list of the items in that note.)

Compliments to this complementarity.

Inconsistencies and incompatibilities between Obsidian and NotePlan

There are a few issues to be aware of when using these two apps together. Some of these may be dealbreakers for you, so please review before charging forward.

NotePlan uses the first line of a note as its title.

With the exception of Daily Notes, all notes in NotePlan are addressable by the first line of text in them. E.g., if you have a note with the filename Some note and the first line is This is some note, NotePlan will think the title is This is some note and links to this note will be of the form [[This is some note]]. This means that when you create a new note in Obsidian, you should re-write the filename on the first line (typically prepended with a # as a title, but it’s up to you.) This also means that you won’t be able to use NotePlan if you use Obsidian YAML to add metadata to your notes in a header.5 This is something I hope NotePlan will change in the future, as it makes more sense to me to use and address filenames. We’ll see!

NotePlan can’t understand Obsidian transclusions (aka embeds).

This just means NotePlan will show the raw text of these lines—i.e., ![[Some note]]. Fortunately, you can still navigate to the targeted link with a click. Just something to be aware of.

NotePlan can’t understand Obsidian heading references and block references.

This is more problematic. An Obsidian heading reference will look like this in NotePlan: [[Some note#Some heading]]. Block references look similar. These statements are easily ignored, but if you forget and try to click them, or if you accidentally click them, you will get a new note titled Some note#Some heading. Frustrating, right? If you use these extensively, it may be extremely annoying.

If you use CloudKit syncing, frequently accessing your notes via the Finder will be more difficult.

The sync method I use (and the one I describe below) uses CloudKit to keep notes synced across platforms. However, CloudKit storage is in Application Support, which is not meant to be easily accessed by the user. If you plan on navigating to your notes in the Finder often, or want to search them via e.g., Alfred, you will need to set up easy ways of getting to that folder (e.g., Finder favourites, editing Alfred’s search scope).

Obsidian doesn’t recognize some of NotePlan’s special todo syntaxes.

One of NotePlan’s neat features is how it handles todos. In Obsidian and NotePlan, lines beginning with - [ ] will be rendered as a task, and - [x] as a completed task. However, NotePlan extends this a bit. - [-] is a dropped task, and - [>] is a rescheduled one (because you can use NotePlan to schedule actions, and it has some intuitive sense of the timelines of your tasks). Obsidian, however, does not render these latter two types of todos. (They still display exactly as they appear, however, so you know what they are!)

NotePlan must remain open on your Mac to push and pull changes between it and Obsidian

NotePlan needs to be open on the Mac to allow “syncing” between Obsidian and NotePlan. NotePlan itself syncs between devices fine. You don’t need NotePlan open on a Mac if you’re going to be switching between iPad and iPhone. But, if you’re switching between NotePlan on iPhone and Obsidian on a Mac, you’ll need to keep NotePlan open on that device.

Setting up Obsidian + NotePlan

This is a little tutorial to help you set up Obsidian and NotePlan to work in tandem. It assumes you don’t have any notes in the NotePlan database when you start. As with any big (or medium, or small) file management exercise, please make a backup of your notes and keep it somewhere away from these apps (e.g., on an external HDD). That way, if anything goes awry, there’s no chance your thinking will be lost.

Use .md files in NotePlan

The first step is to set NotePlan to use .md files, as this is the only plain text format currently recognized by Obsidian. In NotePlan’s preferences, go to the Files tab, and use the extension changer to switch from .txt to .md. (Type “md” in the box, and hit apply.)6 The preferences pane to change file extensions in NotePlan

If you’re planning to use NotePlan on iPhone or iPad, do the same thing in the app on those devices.

Set up Sync in NotePlan

NotePlan’s current beta provides CloudKit, iCloud Drive, and Dropbox syncing options. I prefer CloudKit (it is faster and more reliable than iCloud Drive, and I have lots of storage) but this tutorial may work with the other two options.7

Edit: @ajgxyz on Obsidian’s forum notes that CloudKit affords realtime syncing between a note—you can keep the same thing open in multiple places and the sync does a reasonable job of updating live. Other cloud sync solutions may require a manual refresh.

Go to NotePlan’s Sync tab in preferences next, and choose the sync method you want to use.

If you’re using NotePlan on an iPhone and/or iPad, do the same thing on those devices. If you have any notes in NotePlan on these devices already, you may want to go into the advanced options for CloudKit syncing and use the provided options to make sure your content catches up with itself. (E.g., on your Mac, hit Download All Database Changes, review everything to make sure all your notes are on the Mac, make a backup of the notes, and then on your other devices hit Re-Download Cloud Database. Some experimentation may be necessary to get everything straight. And don’t forget: make backups!)

Set up your Obsidian vault in the NotePlan notes folder

In NotePlan on your Mac, open your sync Advanced options. Select “Open Local Database Folder.” This will open the location of your NotePlan notes in the Finder.

In Obsidian, open the Vault Picker. This happens by default when you first run the app, but if you already have a vault, you can open it by clicking on the little vault icon (on the bottom-left menu bar in the default theme) or by going into the command palette (cmd+p) and searching for “Open another Vault”. Then, choose “Open Folder as Vault”. In the Finder window that shows up, navigate to the NotePlan Local Database Folder we found above. (The easiest way to do this may simply be to drag a folder from the Finder window we opened in NotePlan a moment ago into the Choose Folder pop-up opened by Obsidian.)

This will create a vault in Obsidian using the same folders NotePlan uses. Two of these folders are meaningless in Obsidian: one called com.microsoft.appcenter and another called Filters. Ignore them. The other two folders are intuitive. The Calendar folder is where your Daily Notes will go. The Notes folder is for everything else.

Set your Daily Notes folder and filename syntax in Obsidian

Now that you have a destination for our Daily Notes in Obsidian, you’ll want to make sure Obsidian knows where it is and how to format notes so that NotePlan recognizes them.

First, make sure Obsidian’s Daily Notes plugin is enabled. Go to Preferences → Plugin → Daily Note and make sure the switch is toggled on.

This gives you a settings section for Daily Notes in the left sidebar of Obsidian’s preferences, under Plugin. Here, change your Date Format to exactly YYYYMMDD, and change the New File Location to exactly Calendar. (Feel free to explore Obsidian’s templates, too.)

What your Obsidian Daily Notes settings should look like

Once this is done, Obsidian daily notes and NotePlan daily notes will interoperate.

If you have any, import your old notes

Copy in your previous daily notes (if you have any) into the Calendar folder in Finder (or Obsidian or NotePlan). Note that these will also have to be named the same syntax as above: YYYYMMDD. So, a Daily Note for October 27, 2020 should have the title 20201027. This may involve a bit of effort!

Finally, copy all of your notes files and folders into the Notes folder. (Again, note that the first line of each will need to be the same as the filename.) This may involve a bit of effort, too…

Force a sync on iPhone and iPad

If you’re using NotePlan on iPhone or iPad, go into the Sync preferences, open the Advanced options, and tap “Download All Database Changes”, then give it some time.

Keep NotePlan open on your Mac

See the catch described above. NotePlan needs to be open on your Mac to make sure changes sync between the apps on macOS.

Write away

🎉

That should be it! Create another backup of your newfound setup, then have at it. If anything in these instructions was unclear or incorrect, let me know so I can try to address it.

Enjoy!


  1. Obsidian is free for personal use. You can pay $25 or more for a one-time license that will give you access to early releases and a few other social acknowledgements. Commercial licenses are $50 per user per year. The developers are planning some paid add-on services, such as the ability to publish your notes on the web and an end-to-end encrypted sync service with version history. See the pricing page.

  2. NotePlan 3 will be available via subscription only: $7 USD per month or $60 USD per year for personal use, or $100 USD per year for business use. See the bottom of the NotePlan 3 info page.

  3. Note the gotchas in the next section, however.

  4. I have quite a few of these. I will share them in future posts!

  5. As Obsidian’s plugin system evolves, this may matter more, as some plugins may use YAML metadata to operate.

  6. If you have any notes in NotePlan already, you can tap “Rename Notes” to change the extension of each one to the newly-selected extension.

  7. If you set it up, let me know how it goes. I’m @ryanjamurphy on Twitter.

    Next → → Note titles as API calls Some thinking on the API metaphor of personal notes. ← Previous The best of both worlds: One-click reference metadata for Bookends with Zotero
    Latest posts
    → Cross-post: Intuition is confident abductive-inferential thinking
    → Note titles as API calls
    Why and how to use Obsidian and NotePlan together
    The best of both worlds: One-click reference metadata for Bookends with Zotero
    Distraction Deterrent
    Today’s Plan: A shortcut for planning your day with a text-based list and Fantastical
    DEVONsave: A shortcut to help you clip websites to DEVONthink To Go quickly and cleanly
    Fulcra → A turn of events
    Systemics and design principles in support of Tiago Forte’s PARA framework