I like Markdown precisely because it does not try to solve the world. It is text, it lives on disk, it works with Git, it produces readable diffs, it can be opened in VS Code, Vim, a terminal, or practically any editor, and, most importantly, it does not depend on a platform to keep existing. I can write today, move the folder to another machine a few years from now, and keep working on the same files. That simplicity is one of the format’s best properties, but there is a point where it starts to exact a price: a folder full of .md files is still only a collection of files, even when we already treat it mentally as a related set of notes.
The most obvious example is wiki links. Writing [[arquitetura]] in plain Markdown means absolutely nothing to the filesystem. It is only a character sequence that the author decided to interpret as a link between two things. If arquitetura.md does not exist, nothing happens; if it does, the editor usually does not know; if another note points to it, there is also no reverse index that can say who references that document. The relation exists in the writer’s head, but it still does not exist in the system. That is exactly where, for me, a folder stops being enough.
The traditional solution to this problem is to adopt some PKM tool. Obsidian is probably the best-known example: it resolves wiki links, backlinks, search, graph, plugins, sync, and a huge number of other needs. There is nothing wrong with that. The problem is that there is a considerable distance between “I want my Markdown files to know how to relate” and “I want to adopt a full second brain.” At some point I realized my problem sat exactly in that interval. I did not need to replace the filesystem with a knowledge platform; I only needed to make a Markdown folder stop being dumb.
That is where MD Studio came from.
Version 0.1.0 is a desktop Markdown editor, Linux-first and local-first, built with Tauri 2, React, TypeScript, Rust, and CodeMirror 6. The .deb and AppImage packages are available in the v0.1.0 release. The project was not born from the idea of creating yet another Markdown editor, because editors already exist by the dozen. The point was to establish a few minimal properties that would turn a folder of independent documents into something that could effectively work as a note system, without forcing it to become a vault, a platform, or an ecosystem.
The first of those properties is resolving the links themselves. In MD Studio, [[arquitetura]] and [[arquitetura|Arquitetura do sistema]] are not merely visual elements recognized by the editor. There is resolution to a file, autocomplete, the ability to create the note when the target does not yet exist, and, most importantly, a reverse index that lets you discover which documents point to the note currently open. That is what feeds the backlinks panel. And I made a point of establishing a simple rule: a backlink is a resolved link. If some document contains [[alguma-coisa]], but alguma-coisa cannot be resolved inside the workspace, it does not enter the index artificially just to look as if a relation exists. It is a broken link, and it should keep being treated as such.
That detail looks small, but it touches something I consider important when building this kind of tool: recognizing syntax is not enough; you have to preserve semantics. Painting [[nota]] in another color is trivial; establishing a consistent relation between documents, keeping it when the filesystem changes, and allowing navigation in both directions already turns that into a property of the system.
The second important decision was to treat the workspace as a real boundary. When a folder is opened in MD Studio, that is where the program must operate. The Rust layer works with canonical paths and applies a path fence, preventing file operations from escaping the authorized space through relative-path combinations or other unexpected paths. If I opened /home/elzo/notas, there is no reason for a Markdown editor to decide to explore /home/elzo, /tmp, or anywhere else on the machine. That could be treated as an internal implementation detail, but for me it is part of the contract of local-first software: the user chose a workspace, and that choice must mean something.
The same reasoning shows up in the preview. I have always been bothered by the idea of an editor presenting one interpretation of Markdown while writing and using another pipeline when it is time to export. The predictable result is the document that looked correct inside the program and behaves differently when it leaves it. In MD Studio, preview and HTML export go through the same pipeline. GFM, math, syntax highlighting, and Mermaid follow the same interpretation, and the produced HTML goes through rehype-sanitize. There is no arbitrary JavaScript execution coming from the notes, and no backend is involved in that process. The document is on disk before it is opened, stays on disk while it is being edited, and remains an ordinary file after the program closes. HTML export also uses atomic writes, because producing a valid output and then partially destroying it mid-failure does not seem acceptable to me just because we are talking about a small editor.
Another problem that appears quickly when you work this way is the conflict between the editor buffer and the filesystem. Anyone who uses Git, a terminal, scripts, automation tools, or simply another editor can modify the same file while it is open. If the local buffer is clean, reloading the on-disk version is relatively simple. The situation changes when there are unsaved changes. In that case, silently overwriting one of the versions would be the easiest solution and probably the worst. MD Studio’s filesystem watcher uses debounce and, when it detects that conflict, the decision goes back to the user: reload the file from disk, keep the version in the editor, or save the current content to another file. I do not consider that a major feature; I consider it only a way not to destroy work.
That is also why I tried to keep version 0.1 quite explicit about what it does not do. There is no note graph, cloud sync, JavaScript plugin system, or backend. Opening a .md directly via the operating system’s file association is still a follow-up related to PR #2. Current export is HTML; not PDF. If the README says HTML, then the published feature is HTML. It sounds like a banal observation, but there is a curious tendency in software projects to present roadmap, intention, and implementation as if they were the same thing. I prefer to keep the three apart.
That also helps explain why I do not see MD Studio as a direct competitor to Obsidian. If someone needs a graph, sync across several devices, plugins, mobile apps, and a large ecosystem around notes, there are mature tools whose purpose is exactly that. Building a small version of the same things would only produce a worse Obsidian. The problem I tried to solve is different: finding the minimum amount of infrastructure needed for a Markdown folder to start behaving as a note system without ceasing to be, fundamentally, a Markdown folder.
My current answer is relatively simple: local files, links that actually resolve, a reverse index, navigation, and a consistent representation of the document. After that, an interesting change happens. The files remain independent and can still be opened with cat, Vim, or VS Code, but they stop depending exclusively on the author’s memory to know how they relate. If tomorrow MD Studio disappears, nothing needs to be migrated to recover the notes, because there is no proprietary format hidden underneath them. The program adds behavior to the folder; it does not replace the folder.
Maybe that is what I mean when I call the project minimal PKM, although even that phrase can carry more baggage than necessary. Between a collection of Markdown files and a full knowledge-management platform there is an intermediate layer that rarely gets much attention: resolution, navigation, backlinks, file integrity, and a preview that honestly represents what will be exported. That was the layer I wanted to use day to day.
So I wrote it.