Jasminum: a Zotero add-on for CNKI metadata and Chinese PDF workflows

The gap Jasminum fills in a Chinese-language Zotero library

Zotero's built-in retrieval works well against Crossref, PubMed and most Western publishers. It works badly against CNKI. A PDF downloaded from CNKI often arrives with little or no embedded metadata, and the filename is frequently a numeric identifier rather than a title, so Zotero has nothing to match against. The result is a library full of untitled items that have to be fixed by hand.

Jasminum targets that specific gap. According to the README, its core function is 中文PDF元数据抓取, metadata retrieval for Chinese PDFs, and it states that retrieval currently supports only CNKI, with other data sources described as a future consideration. The audience is therefore narrow: researchers, librarians and students who collect Chinese journal articles and already keep them in Zotero. If your library is mostly English, the metadata retrieval does nothing for you.

The add-on bundles more than retrieval. The README lists a Chinese translator download sourced from the Zotero Chinese community project translators_CN, Chinese citation styles sourced from zotero-chinese/styles, a language setting utility, and Chinese name splitting and merging. Those are small conveniences, but they are the ones that accumulate: a translator that handles CNKI pages correctly removes a manual step every time you capture an article.

How metadata retrieval and local attachment matching actually work

The retrieval flow is manual and menu-driven. After adding a Chinese attachment in Zotero, you right-click the attachment, choose 茉莉花抓取 then 抓取期刊元数据, and a window shows the retrieval result. If more than one search result comes back, the README says you select the closest match yourself and confirm. There is no batch mode described and no automatic background matching, so the design assumes you are willing to check each result. For a library of a few hundred items that is a real cost, and it is the main reason the add-on does not replace a proper import pipeline.

The attachment matching feature addresses a different failure. The README notes that when Zotero Connector captures a Chinese journal article, especially from CNKI, metadata often saves successfully while the attachment fails to download. After you download the PDF or CAJ yourself, you right-click the journal item, go to 小工具 then 在下载文件夹中查找附件, and Jasminum searches your download directory for a file whose name matches the item. The matching rule is stated plainly: similarity between the journal title and the filename. That is a string-similarity heuristic, and the dependency list includes string-similarity, which is consistent with it. Expect it to work when filenames contain recognizable title text and to fail when the filename is a bare CNKI identifier.

Matched files are not simply left alone. The README says successful matches are moved by default into a backup directory at 下载目录/jasminum-backup, and that settings offer two alternatives: delete the matched file from the download directory, or leave it in place. The delete option is described as safe because the attachment is already stored in Zotero, and the README adds a personal recommendation to delete. Moving files out of a download directory is a side effect worth knowing about before you run the command for the first time.

Installing Jasminum and running a first retrieval

The README does not contain install instructions. There is no download link, no .xpi reference and no step-by-step setup in the text provided. What the repository does show is packaging metadata: package.json names the add-on Jasminum, gives the add-on ID as [email protected] and the preference prefix as extensions.jasminum, and the release list shows versioned releases up to v1.1.39 published on 2026-09-02. The README badge states a Zotero target of 8/9. So the practical route is to take the add-on from the project's releases and install it through Zotero's add-on manager, then confirm the version matches your Zotero build. Treat that as the boundary of what can be verified here.

Building from source is documented well enough to attempt, because package.json carries the scripts. The project uses pnpm as its package manager, pinned to [email protected] in the packageManager field, and the build script runs the TypeScript compiler in no-emit mode before the zotero-plugin build step.

pnpm install
pnpm build

For a live development loop the start script launches the plugin scaffold against a Zotero binary, which is configured through a .env file copied from .env.example. That example file expects three paths: ZOTERO_PLUGIN_ZOTERO_BIN_PATH, ZOTERO_PLUGIN_PROFILE_PATH and ZOTERO_PLUGIN_DATA_DIR, with the note that on macOS the binary path is */Zotero.app/Contents/MacOS/zotero and that Windows path delimiters must be escaped as \\.

cp .env.example .env
pnpm start

After the add-on is loaded, the first real use is the retrieval flow: right-click a Chinese PDF attachment, pick 茉莉花抓取 and then 抓取期刊元数据. The README says a window appears with the retrieval result, and that when several results are returned you choose the best match and confirm. If nothing sensible appears, the README offers no troubleshooting section, so the next step is to check that the item is an attachment rather than a standalone note and that the source is CNKI.

The PDF outline editor and its keyboard model

The bookmark feature is the part of Jasminum that has the least to do with metadata, and it is also the most developed. In the PDF reader's left sidebar, a Jasminum bookmark button opens an outline panel. The README describes five toolbar buttons: expand all bookmarks, collapse all, add a bookmark, delete a bookmark, and save bookmark content into the PDF. That last point matters. By default the outline is stored only as a local configuration file, so a reader who edits bookmarks and then opens the same PDF on another machine will not see them. Writing them into the PDF is a deliberate extra click.

Navigation is keyboard-driven, and the README lists the bindings explicitly: up and down arrows move to the previous and next bookmark while skipping collapsed content, left and right arrows expand or collapse a node, space edits bookmark content, the [ key moves a bookmark up a level, the ] key moves it down a level by adopting the preceding sibling as parent, the backslash key creates a new node as a child of the selection, and Delete or Backspace removes a node.

That is a coherent design, but it assumes the user is comfortable with modal-style keyboard editing. There is no mention of drag-and-drop reordering or a multi-select operation, so restructuring a long outline means repeated keystrokes. The dependency on pdf-lib in package.json is consistent with writing outlines back into PDF files, which is the mechanism behind the save button.

Where Jasminum stops being the right tool

The clearest limitation is stated by the project itself: retrieval currently supports only CNKI. Wanfang, VIP and other Chinese databases are not covered, and the README frames additional sources as something under consideration rather than something scheduled. If your workflow spans several Chinese databases, Jasminum handles one slice of it.

The second limitation is the manual confirmation step. Retrieval returns a result window and, on multiple hits, requires the user to pick. There is no documented batch operation for a folder of PDFs, so the add-on scales with your patience rather than with your library size. For a large retrospective import, running a script against a metadata API is likely faster than clicking through results.

The third is the local attachment matching. It relies on filename-to-title similarity, so it inherits every naming convention problem in your download directory. Files named after CNKI download tokens, files with the journal name but not the article title, and files with heavy punctuation will all degrade the match. The README does not describe a confidence threshold or a review step before files are moved or deleted, which is worth weighing before enabling the delete option on a directory you care about.

Jasminum against Zotero's own capture and a plain metadata API

The obvious alternative is Zotero's built-in retrieval plus the Zotero Connector, with translators from the Zotero Chinese community installed directly. That route requires no add-on, but it does not solve the problem Jasminum was built for: when CNKI returns metadata without a downloadable attachment, or when a PDF arrives with no metadata at all, the built-in path leaves you with an incomplete item. Jasminum's 在下载文件夹中查找附件 command exists precisely because that failure is common, and its retrieval command exists because Zotero's own recognizer does not reach CNKI reliably. The difference in approach is that Zotero tries to capture everything at the moment of browsing, while Jasminum repairs items after the fact from a local file.

A second alternative is calling a metadata source directly, for example CNKI's own interfaces or a bibliographic API, from a script. That gives you batch processing and reproducibility, which Jasminum does not offer. What it does not give you is the integration: the results land in a spreadsheet or a BibTeX file that you then have to import, and the outline editing and name-splitting utilities have no equivalent. The two approaches are complementary rather than competing. Use a script for the initial bulk import, and Jasminum for the items that arrive one at a time during normal reading.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-02, with v1.1.39 released the same day. The release history shows a gap: v1.1.37 was published on 2026-05-11, and the next two releases landed on 2026-09-01 and 2026-09-02, so activity clusters rather than flowing steadily. That pattern is normal for a small add-on but it means you should not assume a fix will arrive quickly.

Upgrade cost is mostly determined by Zotero itself. The README badge targets Zotero 8/9, and the add-on ID is fixed at [email protected], so a Zotero major release is the event that forces an update. Preferences live under the extensions.jasminum prefix, which means settings survive a normal add-on upgrade; there is no documented migration step between versions.

The licence is AGPL-3.0-or-later, stated in package.json and as AGPL-3.0 in the repository metadata. The practical consequence is that if you modify Jasminum and let others interact with it over a network, the AGPL's source-disclosure condition can apply. Most individual researchers will never hit that condition, because they install the add-on and use it locally. Anyone forking it into a hosted service should read the licence text rather than rely on this summary. Note also that the add-on downloads translators and citation styles from separate community projects, translators_CN and zotero-chinese/styles, which carry their own terms.

Editorial conclusion

Adopt Jasminum if your Zotero library is mostly Chinese journal articles from CNKI and you want metadata retrieval, local attachment matching and PDF outline editing inside Zotero rather than in a separate tool. Skip it if your sources are English-language databases, if you need metadata from Wanfang or VIP, or if you want a maintained API rather than a right-click menu. Before relying on it, confirm two things: that your Zotero version is covered (the README badge says Zotero 8/9), and that the backup behaviour in 下载目录/jasminum-backup matches what you expect, since the README documents three different handling options for matched files and no rollback procedure.

Frequently asked questions

Official sources

1. Issues
2. l0o0/jasminum on GitHub
3. License: AGPL-3.0
4. README
5. Releases