What problem it solves
A command typed once six months ago, a piece of config, a write-up of why the Wi-Fi dropped — all of it scatters across text files, browser bookmarks and a chat with yourself. You can find it later only if you remember where it is.
Scattered notes
ssh.txt,commands.txt,new server (2).txt- connections between notes live in your head
- search covers one place at a time
- images and diagrams sit apart from the text
An Obsidian vault
- one folder, a note is a file:
SSH keys.md,New server.md - a connection is a link
[[SSH keys]], and a note shows who links to it - search across all notes at once:
tag:#linux path:Linux - an image sits right in the text:
![[network-diagram.png]]
Obsidian has no database of its own: a vault is a regular folder on disk, and the app works with the files in it.
Links, search, properties and plugins sit on top of the files. Close Obsidian and the notes stay, ready for any
editor, grep and git.
How a vault is organized
A vault is a folder that Obsidian opened as a vault. Inside are notes, subfolders, images and PDFs. There’s also a
.obsidian/ folder with settings; Obsidian doesn’t show it in the file list.
notes/
├── .obsidian/ settings of this vault
│ ├── app.json "Files and links", editor
│ ├── appearance.json theme, fonts
│ ├── core-plugins.json which core plugins are on
│ ├── community-plugins.json which community plugins are on
│ ├── plugins/ community plugins, a folder each
│ └── workspace.json open tabs and panes
├── Linux/
│ └── SSH keys.md
├── New server.md
└── network-diagram.png
Each vault has its own settings: in a second vault, plugins, theme and hotkeys start from scratch.
A note is Markdown with a few Obsidian additions:
---
tags: [linux, ssh]
aliases: [authorized_keys]
status: draft
---
Put the key on the server in `~/.ssh/authorized_keys`, set up the client
in [[SSH config#Host|~/.ssh/config]].
The server won't let you in — see [[New server#If it doesn't work]].
![[network-diagram.png]]
- Properties — a YAML block between
---at the start of the file. Obsidian shows it as a table with types: text, list, number, checkbox, date.tags,aliasesandcssclassesare lists; the single-valuetag,aliasandcssclassaren’t read since version 1.9. - A link
[[Note]]— by file name without.md.#Headingleads to a section,#^idto a paragraph marked^idat the end; after|comes your own link text. - An embed
![[…]]— the same link with!: an image, a PDF or a section of another note shows right in the text. - A tag —
#linuxin the text or in thetagsproperty; nested —#linux/ssh.
You can link to a note that doesn’t exist yet: Obsidian draws such a link fainter, and clicking it creates a file with that name. That’s how the vault grows — write a note, link to what isn’t written up yet, and fill it in later.
The Backlinks pane shows every note that links to the current one. Below it, under “Unlinked mentions”, are the notes where its name appears in the text without a link; one click turns such a mention into a link.
Obsidian writes new links as [[…]] (useMarkdownLinks: false) with the shortest path that identifies the file
uniquely (newLinkFormat: "shortest"). As long as there’s only one SSH keys.md in the vault, the link is
[[SSH keys]], without the folder.
Properties can be gathered into tables. The core Bases plugin (since version 1.9) shows notes filtered by properties
— as a table, a list or cards. The view itself lives in a .base file, and the data stays in the notes’ properties.
Core and community plugins
Almost everything Obsidian does is done by plugins. Core plugins are written by the Obsidian team: backlinks, graph, canvas, Bases, templates, daily notes, file recovery. They’re turned on with a toggle in settings under “Core plugins”, and they contain no third-party code.
Community plugins are written by other authors; the catalog opens inside the app. They’re off by default: Obsidian runs in Restricted mode and doesn’t run third-party code. Turn Restricted mode off, and a plugin gets the same permissions as Obsidian itself. The help says so plainly: Obsidian can’t limit a plugin’s permissions; a plugin reads files on the computer, goes to the network and can install other programs. Obsidian checks every plugin version automatically for vulnerabilities and malicious code; popular and flagged ones also get a manual review.
What community plugins add:
Tasks
tasksGathers - [ ] lines from the whole vault by a query in a tasks block: not done, due before tomorrow. The due
date, recurrence and priority are written in the task line itself.
Tag Wrangler
tagsRenames and merges tags across all notes at once — from the tag’s menu in the tags pane.
Codeblock Customizer
codeLine numbers, highlighting of chosen lines and a header above a code block.
A plugin lives in .obsidian/plugins/<id>/: main.js is the code, manifest.json the name and version,
data.json its settings. Delete the folder and the plugin is gone. The notes don’t change, except for what the
plugin itself wrote into them: Tasks due dates stay as text in the lines.
Where it’s used
An IT knowledge base
Commands, pieces of configs, write-ups of breakages — as notes linking to each other. A tag:#docker search gathers
everything on the topic from any folder.
Documentation next to code
Open the repository’s docs/ folder as a vault and add .obsidian/ to .gitignore. If the links are regular
Markdown, the files read just as well on GitHub.
A work log
A daily note — what was done and what broke. Tasks gathers the tasks from all such notes.
Text drafts
Markdown moves into a README or an Astro or Hugo site without conversion, as long as the text has no syntax that only Obsidian understands.
Notes for an AI agent
A vault is a folder of text, and an agent reads and edits it like code. Commit before starting the agent (Clean git status before the agent), and let it rename files only together with the links to them.
Other ways to solve it
Described from their documentation as of October 2026; none were run.
| Where notes live | Connections | Sync | |
|---|---|---|---|
| Obsidian | a folder of .md on disk |
[[…]], backlinks, graph |
paid Obsidian Sync or your own: a cloud folder, Syncthing, git |
| Logseq | the classic version — a folder of .md, the new one — an SQLite database with a read-only Markdown copy |
every line is a block, linked to on its own | a cloud folder or git; the new version has its own sync |
| Joplin | an SQLite database in the app profile, out — by exporting to Markdown | a link to a note by its id: [text](:/id) |
built in: Joplin Cloud, Nextcloud, WebDAV, Dropbox, OneDrive, S3, with end-to-end encryption |
| Notion | the Notion cloud | links to pages, databases with relations | the Notion cloud, sharing for a team |
| VS Code | a folder of .md |
regular Markdown links; [[…]] and backlinks — with the Foam extension |
your own: git |
| If… | Use |
|---|---|
| notes must stay files in a folder, and you want two-way links and plugins | Obsidian |
| you think in outlines and link to every line separately | Logseq |
| you want encrypted sync to your own Nextcloud or WebDAV without plugins | Joplin |
| a team keeps the notes and needs shared databases and access rights | Notion |
| notes are part of a repository, and you work in VS Code anyway | VS Code |
What you get and what it costs
What you get
- Files stay files. Any editor opens a note,
grepfinds it, git stores it (Git). Leaving Obsidian means opening the same folder in another editor; you lose what plugins render and block links#^id. - Two-way connections. You put a link in one note, and it’s visible in both: in the second one, in the Backlinks pane.
- Works offline. Notes, search and the index are on disk. The network is needed for updates, the plugin catalog and Sync.
- Free for any use, work included: the license requires no purchase. The paid parts are the Sync and Publish services (a site made from notes).
- Extensible. What core plugins lack, community ones add; themes and your own CSS snippets change the look.
What it costs
- Part of the syntax only Obsidian understands. GitHub and other editors show
[[…]],![[…]]and block links as text. - A community plugin is code with access to the whole computer. Obsidian doesn’t limit a plugin’s permissions, so check who the author is and whether the plugin gets updates.
- The defaults breed clutter. New notes and pasted images land in the vault root (
newFileLocation: "root",attachmentFolderPath: "/"), and on every rename Obsidian asks whether to update links (alwaysUpdateLinks: false). - Renaming outside Obsidian breaks links. File Explorer, a script or an AI agent changes the file name, Obsidian sees a deletion and a new file, and links keep the old name.
- You assemble sync yourself. There’s no free built-in one: paid Obsidian Sync or your own — a cloud folder,
Syncthing, git. The help advises against running Obsidian Sync alongside another sync on the same vault. Git
sends nothing on its own: you or a plugin run
pullandpush. - The app’s code is closed. The formats are open — Markdown for notes and JSON Canvas for canvases — but the app itself isn’t.
What to change in settings right away
All three are in settings, under “Files and links”:
| Setting | Default | Set to |
|---|---|---|
| Automatically update internal links | off: a question on every rename | on: links are fixed without asking |
| Default location for new notes | vault root | “Same folder as current file” |
| Default location for new attachments | vault root | “In subfolder under current folder” or an attachments folder |
Rename and move files only in Obsidian: the file name is the title above the note’s text, so edit it there, and move files by dragging them in the file list.
Put the vault into git from day one, and you have a point to return to before a big cleanup and before an AI agent
gets to work (Git from scratch). Add .obsidian/workspace.json to .gitignore: it changes every time you switch
tabs.
If it doesn’t work
You renamed a note in File Explorer, and links to it now lead to a new empty note
- Cause
- Obsidian doesn’t know about this rename. From the outside it sees the old file deleted and a new one created, and links with the old name are left dangling. Clicking such a link creates an empty file with that name.
- Fix
- Give the file its old name back and rename it inside Obsidian. If a script or an AI agent moves files, it has to fix the links itself as well.
You renamed a note in Obsidian, but links in other notes kept the old name
- Cause
- “Automatically update internal links” is off by default (
alwaysUpdateLinks: false). Obsidian asks whether to update links, and declining or closing the dialog leaves them as they were. - Fix
- In settings, under “Files and links”, turn on “Automatically update internal links”. Find links that are already dangling by searching for the old name.
Files like Pasted image 20261024103512.png pile up in the vault root
- Cause
- A pasted image is saved where “Default location for new attachments” points. By default that’s the vault root (
attachmentFolderPath: "/"). - Fix
- Set it to “In subfolder under current folder” or a separate
attachmentsfolder. Move the images that have piled up by dragging them in Obsidian’s file list — then the links to them get updated.
On GitHub, [[…]] links show up as plain text
- Cause
- Wikilinks are Obsidian syntax; regular Markdown doesn’t have them. Block links
#^iddon’t work outside Obsidian in any form. - Fix
- For notes that people read on GitHub, turn off “Use [[Wikilinks]]”: Obsidian will write new links as
[text](Note.md).
The community plugin catalog won’t open, a plugin won’t install
- Cause
- Restricted mode is on. Obsidian starts in it by default and runs no third-party code.
- Fix
- In settings, under “Community plugins”, turn off Restricted mode. A plugin gets access to files and the network, so install only what solves a specific task.
You overwrote part of a note or deleted it entirely
- Cause
- Obsidian saves every edit on its own; there’s no “don’t save” button.
- Fix
- The core File recovery plugin, when on, takes snapshots at most once every 5 minutes and keeps them for 7 days outside the vault; open them from the command palette,
Ctrl+P. A deleted note goes to the system trash (trashOption: "system").