MarkDB-Connect: linking a Zotero library to a folder of Markdown notes

The plugin reads your notes and writes tags back into Zotero

MarkDB-Connect is a Zotero plugin, written in TypeScript, and its stated purpose is narrow: it searches a user-defined folder for Markdown files that contain a citation key or a Zotero item key, and adds a colored tag to the corresponding Zotero items.

The mechanism has two halves. The scanning half is a recursive search of a folder you designate in the plugin's preference pane, looking for Markdown files and extracting an identifier from each one. The writing half is a tag on the Zotero item that the identifier resolves to, so a glance at the item list shows which papers have notes and which do not.

Two details make the design usable. A single Zotero item can be linked from multiple Markdown files, so one paper with ten notes still produces one tag. And the plugin also adds a contextual menu entry to Zotero items that opens the linked note in Obsidian, in logseq, or in the system's default Markdown editor.

The intended audience is a researcher who keeps notes in a Markdown vault rather than inside Zotero's own note editor, and who wants the library to reflect that work. The README states the plugin was designed with Obsidian in mind and inspired by the obsidian-citation-plugin workflow, with preliminary support for logseq and Zettlr, and that it can be adapted to other Markdown databases and to other workflows that generate notes linked to Zotero items, such as Zotero's own `Export Note` feature.

Two ways to link a note, and why the choice matters

A Markdown file declares its Zotero item in one of two ways, and the README recommends a different one for each kind of workflow.

With a citation key, the identifier is a short human-readable string such as `shepard1987science`. Citation keys live in Zotero's native `citationKey` field, are set manually in Zotero, or are generated automatically by Better BibTeX. The README recommends citation keys if your notes came from obsidian-citation-plugin, BibNotes Formatter or Obsidian Zotero Integration. The key can be read from the filename, from YAML frontmatter, or from elsewhere in the body of the file.

With a Zotero item key, the identifier is the internal key Zotero assigns to an item. The README recommends this if you created the notes with Zotero's `Export Note` feature, and requires the key to appear in the note in a consistent format.

The extraction rules are configurable, and the defaults are worth knowing. The plugin expects reading note filenames to begin with `@mycitekey`, with anything after that allowed, so `@shepard1987science.md` and `@shepard1987science Toward a universal law of generalization for psychological science.md` both work. If your citation keys contain characters such as `:` or `/`, the filename cannot be used and the key has to be read from the file contents instead. The custom filter option takes a regular expression with a single capturing group, and the documented default is `^@(\S+).*\.md$`. A second option reads the key from a named keyword in the YAML frontmatter.

One note resolves to one item, and the README is explicit about it

The limitation that matters most is a single sentence in the README. Multiple Markdown files can point to the same Zotero item, but a given Markdown file should only be linked to a single Zotero item. A reading note can reference several Zotero items throughout its text, but MarkDB-Connect will link that note to only one citation key or Zotero item key.

That is a design decision rather than a bug, and it follows from how the linking works. The tag on a Zotero item is the visible output, so the plugin needs one unambiguous target per file in order to know which item to tag and which note to open from the context menu. A file with two keys in it produces one link, and the plugin does not document which of them wins.

The practical advice that follows is to give each note file exactly one key, and if a note genuinely covers several papers, either split it or accept that only one of them will show the tag. For a literature review note that cites twenty papers in its body, that means the other nineteen items will not be tagged from that file, which is the behavior a user is most likely to report as a bug.

The tag is colored, which is a small thing that makes the item list scannable, and the plugin supports a dedicated preference pane in Zotero's Settings where the note folder, the extraction mode and the filter conditions live.

Installation is an .xpi file, and Zotero major versions get their own release

There is nothing to build for an end user. The install steps are: download the `.xpi` file from the latest release on GitHub, open Zotero, go to `Tools -> Plugins`, choose `Install Add-on From File...` from the gear icon, pick the downloaded file such as `markdb-connect.xpi`, and restart Zotero.

The version pinning is the part to pay attention to, because the plugin is released per Zotero major version. The README notes that the last release for Zotero 9 was `v0.2.2`, the last release for Zotero 7 and 8 was `v0.1.8`, and the last release for Zotero 6 was `v0.0.27`. The current release, `v0.2.4`, is the one that targets Zotero 10, as the badge in the README states.

That means a user on an older Zotero has to find an older plugin release rather than taking the newest one, and the release list is the only map of which build suits which Zotero. The release history in the repository is consistent with active maintenance: `v0.2.4` on 2026-08-19, `v0.2.2` on 2026-07-22 and `v0.2.1` on 2026-04-28, with the last push on 2026-08-19.

The plugin is MIT licensed, which is the permissive end of the licensing spectrum and is worth stating plainly, since a plugin that reads your notes and writes to your library is code you are running inside your reference manager. Nothing in the licence changes the privacy picture, which the README does not address at all: it does not describe whether the scan is local only, though the described mechanism, a recursive search of a folder you nominate, implies it.

The repository is a plugin template project with a build toolchain

The top level of the repository shows how the plugin is developed. There is an `addon/` directory holding the packaged extension, `src/` for the source, `tests/` split into `unit` and `zotero` subdirectories, and `typings/` for the ambient type declarations. The build is driven by `zotero-plugin.config.ts`, and the project is based on the Zotero Plugin Template, which the README badges acknowledge.

The `package.json` is a TypeScript ESM project, with `"type": "module"` and a version of `0.2.4`, and it uses the `zotero-plugin` CLI for the heavy lifting. The `start` script is `zotero-plugin serve` for development with reload, `build` is `zotero-plugin build && tsc --noEmit` so the build fails on a type error, and `release` is `zotero-plugin release`. The unit tests run under the Node built-in test runner, with the test script pointing at the unit test directory through a glob pattern, and the typecheck target is split into four separate passes, one for the application code, one for the unit tests, one for the Zotero-facing tests and one for repository tooling.

The `config` block is worth a look because it defines the plugin's identity in Zotero. The addon name is `MarkDB-Connect`, the addon ID is `[email protected]`, the preference prefix is `extensions.zotero.mdbc`, and the update manifest is fetched from a raw URL on the `main` branch, with a separate `update-beta.json` sitting beside it for a beta channel.

Development also needs a dedicated Zotero profile, and the `.env.example` file shows how that is configured. Copying it to `.env` and setting the paths is the documented first step:

ZOTERO_PLUGIN_ZOTERO_BIN_PATH=/path/to/zotero
ZOTERO_PLUGIN_PROFILE_PATH=/path/to/development-profile
ZOTERO_PLUGIN_DATA_DIR=
ZOTERO_PLUGIN_KILL_COMMAND=

The first variable points at the Zotero executable, the second at a development profile so your real library is not touched, and the last two are optional, with the data directory defaulting to the profile default.

Compared with putting the notes inside Zotero

The alternative workflow is to write your reading notes as Zotero notes or as Zotero attachments, and manage them inside the reference manager itself. The difference in approach is where the note lives and what the tool has to do about it.

With notes inside Zotero, there is no linking layer at all. A note is a child of the item, the item shows a note count, and the association cannot break because there is no external file to rename or move. The cost is that the notes are locked to Zotero's storage model, and you lose the plain Markdown file, the editor of your choice, and the ability to use the same vault for everything else.

MarkDB-Connect keeps the notes as ordinary Markdown files in a vault, and pays for that with a reconciliation step. The plugin has to search a directory tree, parse identifiers out of filenames, frontmatter or body text, and match them against Zotero records. A citation key that changes, or a note moved outside the configured folder, breaks the link silently, and the tag simply stops appearing. The plugin's own behavior when a key no longer resolves is not described in the README.

There is a third path, which is to keep the notes in Markdown and use the citation key only at the point where the note is written, then never go back. Obsidian Zotero Integration and the obsidian-citation-plugin already write the key into the file as part of the note-taking flow, and the README's recommendation of citation keys is essentially a recommendation to use one of those workflows. MarkDB-Connect then adds the return trip, from the library back to the note, which those tools do not cover.

Editorial conclusion

Use MarkDB-Connect when your reading notes live as Markdown files outside Zotero and you want Zotero to show you, at a glance, which library items you have already annotated, and to open a note straight from the item context menu. Do not use it if you need one note to bind to several items, or if your note naming scheme is loose, because the plugin resolves a single citation key or item key per file and expects the key to be consistently placed. Verify first that your notes carry a citation key or Zotero item key in a form the extractor recognizes, and that the Zotero version you run matches the release you install, since the plugin targets Zotero 10 and older releases are pinned to earlier major versions.

Frequently asked questions

Official sources

1. daeh/zotero-markdb-connect on GitHub
2. Issues
3. License: MIT
4. README
5. Releases