Darragh ORiordan

Obsidian - A free personal data management system on windows, mac and mobile

Photo by Markus Spiske on Unsplash

Obsidian is a free personal data management system based on markdown notes. Because it's based on markdown it's perfect for developers or other power users.

Obsidian has a healthy plugin ecosystem for extending the base functionality. There are plugins for mind mapping, kanban boards, importing amazon kindle highlights, daily notes and using git as a backend.

Obsidian has a powerful search engine that allows you to search for notes by their content, tags, and even the content of the notes they link to. This linking technology is what makes Obsidian so powerful.

Installing obsidian

You can grab obsidian mobile versions from the relevant app store for your device.

On PC or Mac you can download the desktop version from the obsidian website.

Setting up a GitHub Repo Backend

The first thing you should do is set up a GitHub repo as a backend for your notes. This will allow you to sync your notes across devices and also back them up to the cloud (Github).

Create a GitHub repo on GitHub itself. You will likely want this to be private. You can do this by clicking the + button in the top right of the GitHub website and selecting New repository.

Obsidian desktop git plugin can use all the features of a GitHub client. But the mobile version is limited to http only. So you will need to create a personal access token to use with the mobile version.

Creating a personal access token

To create a personal access token go to your GitHub settings and select Developer settings from the left hand menu. Then select Personal access tokens from the left hand menu. Then click Generate new token.

Copy the token and save it somewhere safe. You will need it later.

Adding a .gitignore file

Use the following .gitignore file to ignore the files that obsidian creates. Add this to the repo using your favourite git client.

# Dependency directories

node_modules/
jspm_packages/

# This file is used to keep track of last auto backup/pull

.obsidian-git-data

# exclude workspace cache

.obsidian/workspace

# versions since 1.0 use workspace.json instead
.obsidian/workspace.json

# plugins - we use different plugins on mobile and desktop so we don't want to sync them

.obsidian/plugins
.obsidian/community-plugins.json

# Exclude "bad" names

null\*

# Add below lines to exclude Mac stuff

.trash/
.DS_Store

Setting up the desktop version of Obsidian

Clone the repo you created earlier to your local machine.

When you start Obsidian it will prompt you to set up the vault location. Set it to the repo you created using your usual git tool.

Install the git plugin from the community plugins menu and configure it to use . as the repo location.

I use the following plugins on desktop

  • Advanced Tables
  • Calendar
  • Kanban
  • Git
  • Periodic Notes
  • Tasks
  • Mindmap
  • Kindle Highlights
  • Diagrams
  • Advanced Slides

Setting up the mobile version of Obsidian

Remember that it's better to not check in the plugins folder into obsidian if you're going to use it on mobile. Some plugins just don't make any sense on a small screen device.

To configure Obsidian Git for a mobile device requires a bit of extra work. You need to create a personal access token on GitHub and then use that token to authenticate Obsidian Git.

  1. Install obsidian from the app store of your mobile device
  2. install the Obsidian Git plugin from the community plugin page
  3. Configure the Obsidian Git plugin - Add your username and Github secret access key
  4. Set a "Custom Base Path" folder for your git repo - remember this is the folder that will be synced to GitHub
  5. Now clone the repo - go to the actions menu > choose "clone"
  6. Set the full GH url for repo (remember it must be the https address)
  7. Set the sub directory you added as the Custom Base Path
  8. Now change the settings for Obsidian Git plugin - set auto pull every 5 mins, add the device name (e.g. "Mobile")to the "Commit message auto message" and "hostname" placeholders, turn ON "pull on startup", you must add an author name and an author email.

Because my mobile Obsidian is primarily used for reading and taking notes I use the following plugins

  • Periodic notes
  • calendar
  • Ttasks
  • Kanban

Conclusion

There are often merge conflicts on the mobile version of Obsidian. I've often had to delete and rebuild the whole data set because resolving merge conflicts on mobile is a pain. But it's a small price to pay for the power of Obsidian.

If you really enjoy the tool you can pay Obsidian for a first-class built in synchronisation platform that they support and build directly in to the application.

It's worth reading the docs for Obsidian to get the most out of it. Especially around linking. And take the time to explore all the commands in the command palette. It's a powerful tool!