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

Published on October 13, 2022

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


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


# exclude workspace cache


# versions since 1.0 use workspace.json instead

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


# Exclude "bad" names


# Add below lines to exclude Mac stuff


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


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!

Darragh ORiordan

Hi! I'm Darragh ORiordan.

I live and work in Sydney, Australia building and supporting happy teams that create high quality software for the web.

I also make tools for busy developers! Do you have a new M1 Mac to setup? Have you ever spent a week getting your dev environment just right?

My Universal DevShell tooling will save you 30+ hours of configuring your Windows or Mac dev environment with all the best, modern shell and dev tools.

Get DevShell here: ✨ https://devshell.darraghoriordan.com

Read more articles like this one...

List of article summaries


Building an AI generated game with Stable Diffusion and data from Wikipedia

Last week I released a game called Doodle:ai.

In the game you’re shown AI generated images and you have to guess the Wikipedia topic it used to create the game.


Easiest way to optimise images for web

Here is how I optimise all pngs and jpgs in a folder for publishing to the web.


Start tracking DORA metrics for your team in just 15 minutes with Apache Dev Lake

DORA (DevOps Research and Assessment) metrics are an excellent way for engineering organisations to measure and improve their performance.

Up until now, monitoring the DORA metrics across Github, Jira, Azure Devops etc required custom tooling or a tedious manual process.

With Apache Dev Lake you can get beautiful reporting for DORA metrics on your local machine in as little as 15 minutes (honestly!).

From Google Sheets to Grafana
From Google Sheets to Grafana


A summary of NDC Sydney 2022 Developer Conference

I attended my first in-person conference for more than 3 years last week! NDC is one of the more well-known developer conferences in Australia and New Zealand. It’s a 5 day conference with 3 days of talks and 2 days of workshops.

There’s so much to learn across all the streams so I try to take notes for each of the talks to quickly reference them later. This post contains all my notes. I’ll add the relevant videos to talks later if they’re released.

A reminder that these notes are just my notes. They’re paraphrased and summarised from what the speaker actually said. Each speakers would have provided must more clarity and went into more detail during their pressos!