Obsidian, the note app that keeps your writing in plain files

The phrase local-first gets used loosely, but in Obsidian it has a concrete meaning. The app reads and writes files on disk, and nothing has to travel over a network for it to work. You can install Obsidian, unplug from the internet, and keep using every core feature indefinitely. There is no account to create and no server holding the canonical copy of your notes.

The practical payoff is longevity. A note written in Obsidian today is a UTF-8 text file with a .md extension, and that format has been readable for decades and will stay readable for decades more. If you ever want to leave Obsidian, there is no export step, because there is nothing to export. You copy the folder somewhere else and carry on.

The trade-off is that you inherit responsibilities a hosted service would normally handle. Nothing syncs between your laptop and your phone until you set that up. Nothing is backed up until you arrange a backup. Real-time multiplayer editing, the kind teams expect from a shared web workspace, is not what Obsidian is built for.

It is also worth being precise about openness. Obsidian itself is not open source; the desktop and mobile apps are closed-source software, with the desktop version built on Electron. What is open is the material you produce. Markdown is a widely implemented plain text convention, and the extra syntax Obsidian layers on top of it is simple enough to translate elsewhere.

That distinction matters for privacy too. Because the core of Obsidian does not require an account, ordinary use does not involve uploading your notes anywhere. Anything that leaves your machine leaves because you opted into a paid service or installed a plugin that talks to the network, which is one reason it pays to know what your plugins do.

A vault is the unit everything else hangs from. When you open Obsidian for the first time it asks you to create one, and all that happens is that you pick a directory. Every note, image, PDF, and attachment inside that directory belongs to the vault. Subfolders are ordinary subfolders. There is no database sitting between you and the files, which is why editing a note in another program and switching back to Obsidian shows the change almost immediately.

The one addition is a hidden folder named .obsidian at the root of the vault. It holds settings, enabled plugins, themes, hotkeys, workspace layout, and CSS snippets. Settings in Obsidian are per-vault rather than global, so a research vault can be configured completely differently from a work vault, and copying that folder to another machine reproduces your setup exactly.

Attachments live inside the vault as well. When you paste an image or drag in a PDF, Obsidian copies the file into the vault and inserts a reference to it, and a setting controls whether those files land next to the note, in a folder you name, or in the vault root. Keeping attachments inside the vault is what makes the folder genuinely self-contained.

Many people run more than one vault. A common split is one personal vault and one for work, since that keeps the two sets of settings, plugins, and sync arrangements separate. Obsidian can switch between vaults from a menu, and on desktop you can have several open in separate windows. The counterargument is that links do not cross vault boundaries, so anything you split apart stays apart.

Because a vault is portable, moving one is undramatic. Copy the folder to a new computer, point Obsidian at it, and you get the same notes, the same plugins, and the same layout. The same property is what makes Git, rsync, or a plain external drive perfectly viable ways to keep an archived copy of an Obsidian vault.

Personal Vault/
├── .obsidian/            # settings, plugins, themes, hotkeys
│   ├── plugins/
│   ├── snippets/
│   └── app.json
├── Daily/
│   └── 2024-11-04.md
├── Projects/
│   ├── Kitchen renovation.md
│   └── Reading list.md
└── attachments/
    └── floorplan.png

Notes are written in Markdown, so headings are hash marks, emphasis is asterisks, and lists are dashes. On top of that base, Obsidian supports tables, task checkboxes, footnotes, code fences with syntax highlighting, mathematical notation, Mermaid diagrams, and its own callout blocks for asides and warnings.

There are three ways to look at a note. Live Preview renders formatting as you type while keeping the raw syntax visible on the line your cursor is on, which is the default in Obsidian and the mode most people stay in. Source mode shows the file exactly as it sits on disk. Reading view renders the finished document with no editing affordances. Switching between them in Obsidian is a single hotkey, and the file underneath never changes.

Everything else is keyboard-driven if you want it to be. The command palette exposes every action by name, the quick switcher jumps to a note by fuzzy title match, and hotkeys can be remapped freely. Panes split horizontally or vertically, tabs stack, and you can pull a note into the sidebar to keep a reference in view while writing.

One caution about portability. Standard Markdown moves anywhere, but a few pieces of syntax are specific to Obsidian and its relatives: double-bracket links, embeds written with an exclamation mark, block references, and callout blocks. They are plain text and easy enough to convert, but if you plan to publish through a static site generator it is worth knowing which parts of your writing are Obsidian house style rather than universal.

---
title: Kitchen renovation
status: active
tags: [home, budget]
---

# Kitchen renovation

Quote from the contractor came in under the [[Budget 2024]] ceiling.

- [ ] Confirm cabinet finish
- [x] Measure the alcove

> [!note] Decision
> Going with the shallower island. See [[Floor plan#Island]].

![[floorplan.png]]

Linking is the feature that gives Obsidian its reputation. Typing two opening square brackets brings up an autocomplete list of every note in the vault, and choosing one writes a wikilink. Standard Markdown links work too, but the bracket syntax is faster and is what most Obsidian users settle into.

Links can point at notes that do not exist yet. An unresolved link shows in a dimmed color, and clicking it creates the note on the spot with the title already filled in. It sounds minor, but it changes how writing in Obsidian feels: you name an idea in the middle of a sentence and deal with it later, instead of stopping to decide where a new file should live.

Every link is bidirectional in effect. The backlinks pane lists every note that points at the one you are reading, which means context accumulates on a note without anyone maintaining it. Alongside backlinks sits a list of unlinked mentions, notes where the title appears as text but was never linked, and Obsidian lets you convert those with one click.

Links get more precise than whole notes. You can target a specific heading with a hash mark, target an individual paragraph with a block reference, and give a note aliases in its properties so several phrasings resolve to the same file. Prefixing a link with an exclamation mark embeds the target instead of linking to it, so a paragraph, an image, or an entire note can appear inline inside another.

The graph view is the picture everyone sees in screenshots: notes as dots, links as lines, the whole vault as a constellation. It is genuinely useful for spotting clusters and orphans, and it is honestly not that useful day to day once a vault passes a few hundred notes. Treating the global graph in Obsidian as an occasional diagnostic rather than a navigation tool saves a lot of disappointment.

The local graph is the more practical relative. It shows only the notes within one or two hops of the current file, which reads as a map of the immediate neighborhood. Combined with hover previews, where holding a modifier key over a link shows the target note in a popup, it makes moving through a dense Obsidian vault feel closer to browsing than to opening files.

Obsidian prescribes no structure, which is liberating and also the reason so many people bounce off the app twice before it sticks. You can use deep folder hierarchies, a flat pile of files, tags, links, or any mixture. The one rule worth internalizing early is that structure should follow how you actually retrieve things, not how a productivity system says a vault ought to look.

Properties are the structured layer. Each note can carry a block of YAML frontmatter at the top holding fields like status, author, due date, rating, or a list of tags, and since version 1.4 Obsidian shows those fields as a typed editor rather than raw text. Because properties are typed as text, number, date, checkbox, or list, they become something the app can filter and sort on.

Tags work as lightweight cross-cutting labels, written inline with a hash or listed in properties. They are best for states and categories that cut across folders, things like reference, someday, or a project code. Nesting works with slashes, so a tag hierarchy is possible in Obsidian without folders at all.

Many people also keep index notes, sometimes called maps of content, that do nothing but link out to related material with a sentence of context each. In a link-driven tool such as Obsidian these hand-written indexes usually beat automated lists, because the ordering and the commentary carry information that a folder listing cannot.

Search rounds it out. Obsidian searches the full text of the vault instantly and understands operators for restricting a query to a path, a file name, a tag, a property, a section, or a specific block, with boolean combinations and regular expressions available. Useful queries can be saved into a note as an embedded search block, so a live result set sits inside the document where you need it.

Most of what looks like built-in functionality in Obsidian is delivered as core plugins, first-party modules you can switch on and off individually. Nothing needs to be downloaded for them, and turning off the ones you do not use is a legitimate way to keep the interface quiet. The list below covers the ones people reach for most.

Two core plugins are different in kind because they connect to paid services: Obsidian Sync and Obsidian Publish. They are installed with the app but do nothing until you hold a subscription, and they are covered further down this page.

The design intent behind this arrangement is that a fresh install of Obsidian should be usable as a plain editor, and that everything beyond writing is opt-in. It also means troubleshooting Obsidian is straightforward, since disabling plugins one at a time isolates most odd behavior.

The community ecosystem is the second reason people choose Obsidian. Well over a thousand community plugins are listed in a browser built into the app, searchable and installable without leaving the settings window. They are written in TypeScript against a documented API, and updates arrive through the same panel.

A handful have become close to standard equipment in Obsidian. Dataview turns notes and their properties into queried tables and lists. Templater extends templating with scripting and dynamic values. Excalidraw brings hand-drawn diagrams into the vault. Kanban gives board-style task management on top of Markdown files. Style Settings exposes theme options as toggles instead of CSS. None of them are required, and a vault built only on core features remains entirely reasonable.

There is a security dimension worth stating plainly. Community plugins are third-party code with the same access to your files as the app itself, which is why Obsidian ships with restricted mode enabled and asks you to turn it off deliberately before installing anything. Read what a plugin does, prefer widely used ones, and keep the count low enough that you could name every plugin you have installed.

Appearance is handled the same way. Community themes are installed from within Obsidian, and beyond them you can drop your own CSS files into the snippets folder inside .obsidian and toggle each one from settings. Because the Obsidian interface is rendered with web technology, a snippet can adjust anything from heading sizes to the width of the editor column.

If you write code, the plugin API is open to anyone. A minimal plugin is a manifest file and a compiled script placed in the plugins folder, and Obsidian will load it from your own vault without any review process, which makes small personal automations practical. Publishing to the public Obsidian directory involves a submission and review step.

Canvas, added to Obsidian in 2022, is an infinite board where you can place cards, whole notes, images, PDFs, and web pages, then connect them with arrows and group them into regions. A canvas is saved in the vault as a file with a .canvas extension holding plain JSON, and that format was published as an open specification called JSON Canvas so other tools can read and write it.

In practice Canvas suits the stages of thinking where linear text is the wrong shape: laying out an argument before writing it, mapping a system, arranging research fragments, or storyboarding. Because the cards can be live embeds of real notes, a canvas can act as a working dashboard rather than a static diagram, and edits made on the board go straight into the underlying files.

Bases is the more recent addition, introduced in 2025 as a core plugin. It builds database-style views on top of notes you already have, using their properties as columns and letting you filter, sort, and group the results into a table or card layout. The view is saved as its own file in the vault, so it travels with the notes rather than living in some Obsidian account.

The relationship to Dataview is the obvious question for long-time users. Dataview remains a community plugin with a query language and heavy formatting power, while Bases is first-party, configured through the interface, and supported directly by Obsidian. Many vaults will end up with both for a while, and new Obsidian users generally find the built-in option the gentler starting point.

Since a vault is a folder, anything that keeps a folder in step across devices will keep your notes in step. That is a real advantage and a real chore, because Obsidian does not decide for you and the options differ a lot in effort and reliability, particularly on mobile.

The first-party answer is Obsidian Sync, a paid subscription service. It is end-to-end encrypted with a passphrase only you hold, it keeps version history so you can roll a note back or restore a deleted file, and it lets you choose which folders and file types travel to which device. Because Obsidian Sync is aware of the app's own data, it can also sync settings, themes, and plugin configuration between machines.

Everything else is a general-purpose file sync tool doing a job it was not written for. iCloud Drive is the smoothest free route for people entirely inside the Apple ecosystem. Syncthing gives peer-to-peer sync with no cloud middleman for those who enjoy configuring it. Git suits developers and adds a proper commit history, though on phones it needs a community plugin and some patience. Dropbox and similar services work fine on desktop but are awkward to attach to Obsidian on mobile.

Whatever you choose, close the vault before a device sleeps for a long stretch and let one machine finish syncing before you edit the same note on another. Conflicts in Obsidian usually surface as duplicate files with a suffix rather than lost text, but merging them by hand is tedious enough to be worth avoiding. And a sync service is not a backup, because a deletion propagates just as fast as an edit.

If you are undecided, the pragmatic move is to start with whatever free tool you already run and switch to Obsidian Sync only if mobile turns painful. Nothing about the vault changes when you switch, since every method is moving the same folder.

Obsidian Publish is the second paid service. It hosts selected notes from a vault as a website, choosing note by note what becomes public, and it preserves the things that make the vault work: wikilinks, embeds, hover previews, backlinks, search, and an interactive graph. Sites can run on a custom domain, and republishing is a matter of pushing changed files from within Obsidian.

It is not the only route to a public site. Because the vault is Markdown, static site generators and open source publishing projects can build from the same folder, usually with more control over templates and no subscription, in exchange for maintaining a build pipeline. The trade is convenience against flexibility, and Obsidian Publish exists mainly for people who would rather write than deploy.

Capture runs in the other direction. The Obsidian Web Clipper is a free browser extension that saves an article, a selection, or a set of highlights straight into a vault as a Markdown note, with configurable templates that can fill properties such as source URL, author, and date. It turns the vault into a reading archive without the copy and paste ritual, and the clipped notes behave like any other note in Obsidian.

Obsidian runs on Windows, macOS, and Linux, with Linux builds distributed in several package formats, and there are Obsidian apps for iOS and Android. The mobile apps open the same vault, run the same community plugins where the plugin author supports mobile, and use the same file format, so a note captured on a phone is immediately a note on the laptop once sync catches up.

Mobile does have a different character. The interface is condensed to a single pane with a swipe-driven sidebar and a customizable toolbar above the keyboard, and heavy features such as the global graph are less pleasant on a small screen. Most people use Obsidian on the phone for capture and reading and do their structural work at a desk.

Accessing the vault from mobile requires the folder to be reachable by the app, which is where the sync decision from the previous section becomes concrete. On iOS the practical choices are iCloud Drive or Obsidian Sync; on Android there are more ways in, including pointing Obsidian at a local folder on the device itself.

The application is free to download and use, and that includes use at work. Obsidian previously required a paid commercial license for people using it inside a company, and in 2025 that requirement was dropped, leaving an optional commercial license for organizations that want added support and assurances. Nothing about the free version of Obsidian is time limited or feature gated in the usual trial sense.

Revenue comes from two optional subscription services, Obsidian Sync and Obsidian Publish, both billed monthly or annually with a discount for paying yearly, and from a one-time supporter license called Catalyst. Catalyst gives access to early insider builds and community recognition rather than extra features in the shipping app. Because prices change, check the current figures in the account settings inside Obsidian rather than trusting a number quoted anywhere else.

Neither service is required to use Obsidian well. Plenty of long-running vaults sit on free file sync and a scheduled backup, and Obsidian behaves identically whether or not a subscription is attached to it.

The business model has a bearing on the longevity argument. A company selling optional services around a free local app is not obliged to hold your data hostage, and since Obsidian keeps the notes as files on your own disk, a lapsed subscription costs you syncing, not access.

Obsidian is a good match for people writing mostly for themselves over a long horizon: researchers, students, writers, developers, analysts, lawyers, anyone whose notes need to be findable in five years. It rewards the habit of writing things down in prose and connecting them, and Obsidian is comfortable in vaults holding thousands of files.

It is a weaker match when the main requirement is several people editing the same document at once, structured project management with assignments and permissions, or a polished shared wiki that non-technical colleagues maintain. Obsidian can approximate those with plugins and a shared folder, but a tool designed for collaboration will do them better, and there is no shame in running Obsidian for personal thinking beside a hosted workspace for the team.

The other honest caveat is the learning curve. The blank vault gives no guidance, the settings run deep, and the plugin catalog invites tinkering. People who succeed with Obsidian usually start with a folder, a daily note, and links, and let structure emerge over months. People who bounce off Obsidian usually try to build the perfect system in week one.

There is no correct Obsidian configuration, but there is an order of operations that spares most beginners a wasted month. The goal for week one is to have real notes in a real vault, not a finished system.

1. Step 01

   Install Obsidian for your platform and open it. Nothing needs an account, and the download works the same on desktop and mobile.

2. Step 02

   Create a vault in a folder you already back up, and give it a name you will still like in a year. Resist the urge to build a folder tree before there is anything to file.

3. Step 03

   Write ten notes about things you actually care about before changing a single setting in Obsidian. Turn on daily notes if a dated page helps you start.

4. Step 04

   Start linking those notes with double brackets, then open the backlinks pane and watch context assemble itself. This is the moment Obsidian usually clicks.

5. Step 05

   Only then decide how the vault reaches your other devices, and add Obsidian plugins one at a time as specific frustrations appear.

After that first week, the useful question is never which plugin to add next but which part of your work is still living outside Obsidian and would be better off inside it.

Name notes as if you were writing a link, because in Obsidian you will be. A title that reads naturally inside a sentence makes wikilinks legible, and it beats an ID scheme for anyone who is not already committed to one. Set the attachment folder early, since moving hundreds of images later is not fun even in a tool as file-friendly as Obsidian.

Keep property names consistent from the start. Filtering and sorting in Obsidian depend on the same field appearing under the same name across notes, and a vault with status, Status, and state as three separate properties will disappoint you the day you try to build a view over it.

Back the vault up somewhere your sync does not reach. A weekly copy to an external drive or a Git repository protects against the failure sync cannot cover, which is deleting something and not noticing for a month. Given that Obsidian stores plain files, this is a one-line script or a drag of a folder.

Finally, review occasionally rather than continuously. Open a random note, check the orphans in the graph, prune plugins you no longer use, and rewrite an index note that has drifted. Obsidian gives you no automatic maintenance and no algorithmic feed, and a short deliberate pass every few weeks is what keeps a large Obsidian vault from turning into an attic.