basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    Obsidian: what it is and how it stores notes

    Obsidian is a note editor on top of a regular folder: a note is a .md file, a connection between notes is a [[…]] link. On top of that the app adds backlinks, search across the whole vault, properties and plugins. The files stay readable without Obsidian: any editor opens them, grep finds them, git stores them.

    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, aliases and cssclasses are lists; the single-value tag, alias and cssclass aren’t read since version 1.9.
    • A link [[Note]] — by file name without .md. #Heading leads to a section, #^id to a paragraph marked ^id at 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 — #linux in the text or in the tags property; 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

    tasks

    Gathers - [ ] 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

    tags

    Renames and merges tags across all notes at once — from the tag’s menu in the tags pane.

    Codeblock Customizer

    code

    Line 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

    The main case

    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, grep finds 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 pull and push.
    • 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 attachments folder. 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 #^id don’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").