Mktero

English · 简体中文

Read Zotero PDFs as source-linked Markdown.

Mktero is a restartless Zotero extension for Zotero 7, 8, 9, and 10. It sends a local PDF to your selected OCR service, MinerU or Mistral OCR 4.1, when needed, then opens the resulting Markdown, formulas, tables, figures, citations, and annotations in a temporary, reading-first Zotero tab. A content-addressed local cache avoids repeating conversions for the same PDF and parser profile.

Download · Product page · Documentation · Community

Important

Mktero is in beta. On a cache miss, the complete PDF is sent to the selected conversion provider, so configure either a MinerU API Token or a Mistral API Key. Optional AI translation sends protected Markdown batches to the provider configured by you. Review Privacy and data handling before processing sensitive documents.

Contents

• Features
• Quick start
• Documentation
• Privacy
• Development
• Community
• Contributing
• License

Features

Reading

• Reflow OCR output, multi-column text, formulas, tables, figures, lists, and code into a continuous academic reading document.
• Hide publisher mastheads, first-page copyright notices, repeated headers and footers, and page numbers, and keep reliable page/region mappings so text, formulas, tables, and figures can jump back to their PDF source. A PDF text selection can open its Markdown paragraph when that mapping is unique.
• Browse the outline or a figure/table index, preview citations, affiliations, figures, and tables, and find text in the body with Cmd/Ctrl+F.
• Rebuild figures from the local PDF when layout evidence, page coordinates, and Markdown ranges agree. Restoration runs in a background worker and replaces placeholders in place, so slow figures never block reading.

Annotations and translation

• Display Zotero PDF highlights and underlines in Markdown, and create, recolor, comment on, or delete annotations.
• Correct recognition errors in existing paragraphs, headings, and GFM table cells without modifying the immutable OCR result.
• Translate a complete article through a configured Vercel AI SDK provider and switch between Original, Translation, and continuous Bilingual reading; look up a selected term or passage on demand.

Library and export

• Check whether each Markdown reference already exists in any accessible Zotero library, copy a reference from another library, and import missing metadata with an optional public PDF attachment.
• Explore direct reference relationships among papers already in the current Zotero library, using Semantic Scholar, OpenCitations, and OpenAlex when identifiers are available.
• Save a portable Zotero snapshot, or export corrected Markdown and its extracted figures to a local folder or an Obsidian vault.
• Show a Markdown column in the item list when this computer still has a readable cached conversion for the current settings. While a PDF is queued or converting, that column shows a session-only spinner. The ready marker stays in the Zotero profile, does not modify the item, and does not sync.

The interface follows Zotero's English or Simplified Chinese display language. Other locales fall back to English.

Quick start

Tip

Install the XPI, open Settings -> Mktero, add an OCR key, then open a PDF and click the Mktero icon in the reader toolbar.

Requirements

• Zotero. Desktop 7.0 through 10.0.*.
• PDF. An attachment downloaded and available as a local file.
• OCR. An API key for MinerU cloud or Mistral. MinerU can instead use a self-hosted MinerU 4.0 service; its API key is optional.
• Network. Access to the selected conversion API, or to the configured local MinerU service.

MinerU and Mistral control file-size, page-count, quota, and service-availability limits. See the MinerU API documentation or Mistral OCR documentation for current limits.

Install

1. Download the latest mktero-<version>.xpi from GitHub Releases.
2. In Zotero, open Tools -> Plugins.
3. Open the gear menu and choose Install Add-on From File....
4. Select the XPI and follow Zotero's prompts.

Formal GitHub releases receive automatic updates through Zotero. Drafts and prereleases are not offered as automatic updates.

Configure

Open Settings -> Mktero after installation, choose a conversion provider, and enter its API key. AI features and reading options are optional; each AI provider keeps its own model, key, and related settings. Credentials are stored as ordinary, unencrypted preferences in the active Zotero profile.

See Configuration for every setting and Privacy and data handling for what is sent where.

Open a PDF

1. Start from the PDF or library item you already have:

   • Open a PDF in Zotero and click the Mktero file icon in the reader toolbar.
   • Right-click a PDF or library item and choose Read as Markdown with Mktero.
   • Select several items and choose Prepare selected Markdown to queue them without opening a tab for each one.
   • Right-click a collection and choose Prepare collection Markdown to prepare only that collection's own PDFs, not its subcollections. A single item still uses Read as Markdown with Mktero.

2. Follow the upload, conversion, and download progress in the temporary Mktero tab. A valid cache entry skips the remote conversion. A batch uses Zotero's progress window; minimizing it keeps preparation running.

3. Use the outline, find, citations, figure/table previews, source links, and Zotero notes panel to navigate the document.

Note

Mktero tabs are session-only and are not restored after Zotero restarts. Closing a tab does not cancel an in-progress conversion; it continues in the background and appears in the preparation window. Shutting down the extension cancels active conversion and translation requests. Each uncached PDF in a batch is sent the same way as a single conversion. Reopening the same PDF and conversion profile restores the last reading paragraph.

Documentation

Guide	What it covers
Configuration	Every setting and its default
Reading and annotation workflows	Corrections, annotations, AI translation, citations, references, snapshots, and export
Figure pipeline	How figures are rebuilt from the local PDF
Privacy and data handling	What Mktero sends and where it is stored
Limitations	Supported PDFs, navigation, and resource limits
Development	Build, test, figure corpus, and contributing

Privacy

• On a cache miss, the complete PDF is sent to the selected MinerU cloud, configured local MinerU service, or Mistral provider.
• Credentials, cached Markdown and figures, corrections, translations, and reading positions are stored unencrypted in the active Zotero profile and are not synced by Mktero.
• Reference, citation, and translation requests are bounded and local-first; logs never contain API tokens, presigned URLs, PDF bytes, or authenticated responses.

Full details and the complete data table are in Privacy and data handling.

Development

Use the Node.js version in .node-version, currently 24.15.0. Node.js 25 is outside the supported dependency range.

npm ci
npm run check
npm test
npm run build

See Development for the figure corpus regression.

Community

Usage questions can go to the QQ group, WeChat, or Discord. Ideas, reading workflows, and beta feedback belong in GitHub Discussions. Reproducible bugs belong in GitHub Issues.

Do not paste API keys, PDF contents, or logs that contain credentials into the QQ group, WeChat, Discord, issues, or pull requests.

QQ is a group: scan the code, or search 616518076 in QQ.

QQ

WeChat

Contributing

Pull requests are welcome. For changes to runtime behavior, run the complete verification commands above and include tests for the affected behavior.

• Ideas, reading workflows, and beta feedback: GitHub Discussions
• Usage questions: Community
• Reproducible bugs: GitHub Issues

Please keep credentials, private PDFs, and other sensitive data out of the QQ group, WeChat, Discord, issues, pull requests, and logs.

License

MIT © 2026 Tony