Doc2X Zotero Plugin User Guide

The Doc2X Zotero plugin now supports Zotero 9. New users should use Zotero 9. If you still use Zotero 7 or 8, download the separate compatibility build from the download page.

Supported Versions

Zotero version	Plugin option	Recommendation
Zotero 9	Zotero 9	✅ Recommended
Zotero 7/8	Compatible with 7/8	⚠️ For short-term use in existing environments only
Zotero 6	None	❌ Not supported

Note: The Zotero 9 build and the Zotero 7/8 compatibility build are different packages. Download the package that matches your current major Zotero version.

Before You Start

You need the following components:

• Zotero 9 (recommended), or an existing Zotero 7/8 installation
• Doc2X desktop client
• The Doc2X Zotero plugin .xpi package
• A Doc2X account

The latest plugin no longer depends on Better Notes for Zotero. You do not need to install Better Notes.

Download and Install the Plugin

Step 1: Download the Correct Build

1. Open the Doc2X client and plugin download page.
2. Find the "Zotero 插件" (Zotero Plugin) card.
3. Select the build that matches your Zotero version:
   • Zotero 9: keep "Zotero 9" selected and click "立即下载" (Download Now).
   • Zotero 7/8: switch to "兼容 7/8" (Compatible with 7/8), then click "立即下载".
4. Keep the downloaded .xpi file as-is. Do not extract it.

Recommended Build for Zotero 9

Compatibility Build for Zotero 7/8

If your browser tries to open the .xpi as a Firefox extension or reports that the file is corrupted, download it with Chrome or Edge and confirm that the filename still ends in .xpi.

Step 2: Install the Package in Zotero

1. Open Zotero.
2. Go to Tools → Plugins.
3. Drag the downloaded .xpi file into the Plugins window.
4. If drag-and-drop is unavailable, click the gear button in the upper-right corner, select Install Plugin From File…, and choose the .xpi file.
5. Confirm the installation and restart Zotero when prompted.

After installation, the Doc2X plugin appears in the plugin list. See the official Zotero plugin installation guide for additional details.

Update an Existing Installation

Use the following sequence when updating the plugin:

1. Uninstall the old Doc2X plugin in Zotero's plugin manager.
2. Quit Zotero completely.
3. Reopen Zotero.
4. Install the new .xpi file that matches your current major Zotero version.
5. Restart Zotero again.

After upgrading from Zotero 7/8 to Zotero 9, remove the 7/8 compatibility build before installing the Zotero 9 build.

Connect the Doc2X Client

Step 1: Install and Sign In to the Client

Install the Doc2X desktop client from the download page, then start it and sign in to your Doc2X account. Keep the client running while using the Zotero plugin.

Step 2: Get a Token

1. Open the Zotero settings:
   • Windows: Edit → Settings → Doc2X.
   • macOS: Zotero → Settings → Doc2X.
   • You can also press Ctrl/Cmd + , to open Settings.
2. Click Get Token.
3. The plugin retrieves authorization from the locally running Doc2X client.
4. Confirm that the token status and available parsing quota are displayed.

If token retrieval fails, make sure the Doc2X client is running and signed in. Restart the Doc2X client and Zotero, then try again.

Configure Parsing and Translation

The following options are available on the Doc2X settings page in Zotero.

Translation Models

The plugin supports free and paid translation models. The available model list is loaded dynamically from the server, so refer to the options currently shown in the plugin.

• Free models do not consume Premium Points.
• Paid models consume Premium Points according to the rules shown on the page.

Target Languages

Supported target languages include Chinese, English, Japanese, French, Russian, Portuguese, Spanish, German, Korean, and Arabic.

Translation Exclusions

You can skip the following content during translation:

• Tables
• Code
• Figures
• References

Output Formats

• Text output: Original MD, translated MD, bilingual MD, original HTML, translated HTML, bilingual HTML, translated PDF, and bilingual PDF.
• Layout-preserved output: Original MD, layout-preserved translated PDF, and layout-preserved bilingual PDF with the original on the left and translation on the right, or vice versa.

Glossary

You can select a custom glossary to keep terminology consistent. After configuring the options, select I have completed parsing & translation configuration.

Use the Plugin in Zotero

Right-click a PDF attachment that has a parent item to open the Doc2X menu:

• Translate PDF to Md Notes: Translate the PDF and import the result as a Markdown note.
• Parse PDF to Md Notes: Parse the PDF without translation.
• Translate with Layout Preservation: Translate the PDF while preserving its original layout.
• Open Error Log Directory: Open the plugin logs for troubleshooting.

For notes generated by Doc2X, the context menu also provides:

• Doc2X: Preview Markdown: Preview the Markdown source.
• Doc2X: View in Web: Open the parsing or translation result in a browser.

Costs

• Parsing consumes parsing pages. The current parsing discount is applied automatically, and no parsing model needs to be selected in the plugin.
• Translation with free models does not consume Premium Points. Paid models consume Premium Points according to the applicable rules.

If parsing succeeds but translation fails:

1. Select the corresponding result in the Doc2X client's left task list.
2. Click Continue Translation.
3. When it finishes, use the export option in the upper-right corner to export the result to Zotero.

This continues the translation charge only and does not deduct the parsing pages again. Do not start the same translation task again from Zotero.

Important Notes

Large Files

• Avoid translating PDFs longer than 100 pages directly from Zotero.
• Plugin status updates may be less visible for long documents. Check the Doc2X client for real-time progress.
• An unchanged status does not necessarily mean the task is stuck. DeepSeek and other slower models may take longer to finish.

Plugin-to-Client Connection

The plugin communicates with the locally running Doc2X client through SSE (Server-Sent Events) and automatically detects the local client port. Keep the client running; the plugin automatically attempts to reconnect if the connection is interrupted.

System Compatibility

Operating system	Supported versions	Zotero version	Status
Windows	Windows 10/11	Zotero 9	✅ Supported
Windows	Windows 10/11	Zotero 7/8	✅ Compatible
Windows	Windows 10/11	Zotero 6	❌ Not supported
macOS	Apple silicon	Zotero 9	✅ Supported
macOS	Apple silicon	Zotero 7/8	✅ Compatible
macOS	Intel	-	❌ Not currently supported

Video Tutorial

Watch the earlier video tutorial

The video uses an older plugin release. It includes a Better Notes installation step and does not show the Zotero 9 download option. Follow this guide for the current installation and version-selection process.

Frequently Asked Questions

Which Zotero versions are supported?

Zotero 9 is recommended. Zotero 7/8 can use the compatibility build on the download page. Zotero 6 is not supported.

Can I install the "Compatible with 7/8" build in Zotero 9?

This is not recommended. For Zotero 9, download the default "Zotero 9" build. The two packages target different major Zotero versions.

What should I do if the plugin stops working after upgrading from Zotero 7/8 to Zotero 9?

Uninstall the 7/8 compatibility build, quit and reopen Zotero, then install the Zotero 9 .xpi package.

Do I still need Better Notes?

No. The latest Doc2X plugin no longer depends on Better Notes for Zotero.

How do I clear the plugin cache?

Click Clear Cache on the Doc2X plugin settings page. This resets the plugin settings while preserving authorization information.

What if the plugin cannot connect to the Doc2X client?

Make sure the Doc2X client is running and signed in. The plugin automatically detects the local client port and retries the connection. If it still cannot connect, restart the Doc2X client and Zotero, then try again.

Feedback

For other issues, contact us.