Obsidian has earned its following: local Markdown files, fast search, links and a graph, and a plugin for nearly everything. Many developers keep their own notes in it and want the same for the team: specs, runbooks and decisions as plain files, versioned, readable by any tool and by any AI agent. Then the team tries to share one vault, and the edges show.
This post looks at where Obsidian stops being the easy choice for a software team, what docs-as-code should look like, and how Apiboo approaches it: documents and boards that live next to your API collections and are written into your Git repository as Markdown and YAML. We make Apiboo, and the limits section says what it does not do, including the plugin ecosystem that nothing else matches.
Where Obsidian gets awkward for a team
- Sharing a vault needs Obsidian Sync on every collaborator’s account, at a per-user price, or a Git plugin and a repository that everyone has to pull and push by hand. Two people editing the same note at the same time is a merge conflict either way.
- A vault is files in a folder. Access control is whatever the folder or the repository gives you, with no notion of a team space versus personal notes.
- Tasks live inside notes (checkboxes, or a Kanban plugin). That is fine for one person and thin for a team that needs lists, assignees, due dates and comments.
- The API collection the docs describe lives in a different app, with its own storage. The link between a spec and the request it specifies is a URL at best.
- The good news: Obsidian’s commercial licence has been optional since February 2025, so the licence itself is no longer the obstacle; sharing is.
What docs-as-code should look like for a dev team
If the team’s documentation is going to live in Git, four things make it work rather than merely possible:
- Plain Markdown, one file per page, in a folder structure a person can browse on GitHub without any app.
- An editor people actually write in: slash commands, tables, code blocks, images, subpages. Raw Markdown in an IDE scares off half the team.
- Tasks in the same repository, as files, so a pull request can touch the spec and the task that asked for it.
- Live editing for the team’s shared pages, with Git as the history and the review channel, not as the only way to collaborate.
How Apiboo writes docs and tasks into your repo
In Apiboo, Documents is a block editor with a slash menu (headings, quotes, code blocks with highlighting for sixteen languages, tables, to-do lists, images, YouTube and Vimeo embeds, subpages), and it takes Markdown as you type: #, >, -, 1., - [ ], three backticks and inline bold, italic and code. Pages sit in a folder tree with personal pages, pages kept on this device only, and one section per team. Team documents are edited live by everyone on the team.
Connect My projects, boards & documents to a repository on the Git page and Apiboo writes documents/ with every page as a .md file, subpages in a folder named after their page and images under documents/media/; boards/<name>/ with a board.yaml for the lists and labels and one Markdown file per task in tasks/, including its comments; and projects/ with one YAML file per project and how they link together. Other files in the repository, such as a README or your code, are never touched.
Apiboo never commits or pushes by itself. Sync now commits and pushes, Pull gets the repository’s changes into Apiboo, and if a pull would delete more than ten items at once, Apiboo keeps them and tells you, so a mistake in the repository cannot wipe your pages. A secret check runs before every commit.
Docs, tasks and APIs that know about each other
The part Obsidian cannot offer is proximity. In Apiboo the Bookshop spec, the Bookshop board and the Bookshop collection are in the same app, and the Graph shows how they connect: page links appear as Links to and Linked from, and a project groups its documents, tasks, requests and the repositories of its code. An AI agent connected over Apiboo’s MCP server can ask for a whole project in one call and read the spec, the open tasks and the requests before it touches anything, with the vault and every secret out of reach. That is the context a coding agent needs and a folder of notes cannot give it.
What Apiboo does not do
Be honest with yourself about these before you move a vault:
- No plugins, no community themes, no Dataview. Obsidian’s ecosystem is the reason to stay, and nothing here replaces it.
- The editor is not a Markdown source editor. You type Markdown shortcuts and get blocks; you do not see the raw file inside the app. The raw file is what lands in the repository.
- Documents are stored in the app’s own database and written to Git by Apiboo; the repository is a synced copy of your pages, not the folder the editor opens.
- Git is in the desktop app only, and a team’s history has to live on a server; This device only is for your own pages.
- Conflicts are resolved per file, yours or theirs, not line by line inside Apiboo.
Who should use what
- Personal knowledge base, heavy plugin use → Obsidian, no question.
- A team that already writes docs in the repository and reviews them in pull requests → keep Markdown in Git; a plain editor and CI are enough.
- A dev team that wants a real editor, tasks and the API collection in one place, with Markdown and YAML in its own repository as the record → Apiboo.
- The related guide on collections in Git is at apiboo.com/blog/api-collections-in-git, and the board side at apiboo.com/blog/kanban-board-for-developers.
Try it with your own work
Create a document, write a spec with the slash menu, add a board with three tasks, then open the Git page and connect a repository: the next Sync now shows you the Markdown and YAML it wrote, in a layout you can read on GitHub.
Download Apiboo for Windows, macOS or Linux at apiboo.com/download. It is free to start, with no card and no account: every tool runs on your own machine, and you only sign in when you want sync or a team.