Status: 🚧 In Development - Project setup complete, implementation in progress

Bidirectional sync between Zotero and Supernote Manta via Google Drive. Automatically export PDFs, import annotations, and manage collections across both systems.

zot-sn solves the workflow gap between Zotero and Supernote e-ink tablets. Currently, users rely on manual workflows like ZotMoov for one-way PDF export, but there's no support for:

• ✅ Syncing annotations back from Supernote to Zotero
• ✅ Managing collections bidirectionally
• ✅ Automatic synchronization without manual intervention

This plugin provides a complete bidirectional sync solution.

• Automatically export PDFs from Zotero to Google Drive
• Mirror Zotero collection hierarchy in folder structure
• Configurable filename patterns
• Smart sync (only copy changed files)

• Parse Supernote .mark files
• Convert annotations to Zotero format:
  • Highlights → Zotero highlights
  • Text notes → Zotero notes
  • Ink annotations → Zotero images/ink
• Preserve original .mark files as attachments

• Detect folder changes and update Zotero collections
• Detect file moves and update item collections
• Handle deletions with user confirmation
• Maintain consistent organization

• Automatic background sync (configurable interval)
• Manual "Sync Now" button
• Conflict detection and resolution
• Status indicator showing sync state
• Comprehensive sync logs

The plugin is structured in layers:

┌─────────────────────────────────────┐
│         UI Layer                    │
│  Preferences | Status | Dialogs     │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│      Sync Engine (Core)             │
│  Orchestration | Scheduling         │
└────────┬────────────────┬───────────┘
         │                │
┌────────▼──────┐  ┌──────▼───────────┐
│  PDF Exporter │  │  Annotation      │
│               │  │  Importer        │
└───────────────┘  └──────┬───────────┘
                          │
                   ┌──────▼───────────┐
                   │  .mark Parser    │
                   │  (SupernoteSharp │
                   │   or PySN)       │
                   └──────────────────┘

See ARCHITECTURE.md for detailed technical documentation.

• ✅ Set up plugin boilerplate
• ⏳ Configure build system
• ⏳ Implement basic PDF export
• ⏳ Create preferences pane

• Evaluate SupernoteSharp vs PySN
• Integrate selected parser
• Build annotation converter
• Test with sample files

• Implement file monitoring
• Build sync engine
• Add collection management
• Implement conflict detection

• Build sync dashboard
• Create conflict resolution dialogs
• Enhance settings panel
• Add status indicators

• Beta testing
• Performance optimization
• Cross-platform testing
• Documentation and release

See PLAN.md for the complete development plan.

The project addresses several technical challenges:

1. .mark file format - Proprietary, reverse-engineered format
2. Annotation mapping - Different capabilities between Supernote and Zotero
3. Sync conflicts - Bidirectional changes require conflict resolution
4. Performance - Large libraries need optimization
5. Cross-platform - Must work on Windows, macOS, and Linux

See CHALLENGES.md for detailed solutions and mitigation strategies.

Once released, installation will be:

1. Download the .xpi file from Releases
2. In Zotero: Tools → Add-ons → Install Add-on From File
3. Select the downloaded .xpi file
4. Restart Zotero
5. Configure in: Edit → Preferences → zot-sn

1. Google Drive Folder: Point to your Google Drive sync folder
2. Collections: Select which Zotero collections to sync
3. Sync Interval: How often to automatically sync (default: 10 minutes)

• Conflict Resolution: Choose automatic resolution strategy
• Filename Pattern: Customize exported PDF filenames
• Parser Selection: Choose between SupernoteSharp, PySN, or custom

• Zotero 7.0 or later (8.0 recommended)
• Google Drive desktop app (or equivalent sync client)
• One of:
  • .NET 6+ runtime (for SupernoteSharp)
  • Python 3.7+ (for PySN)
  • Neither (if using custom JS parser)

• Supernote Manta (primary target)
• Supernote A5X (should work)
• Supernote A6X (should work)

# Clone the repository
git clone https://github.com/btromm/zot-sn.git
cd zot-sn

# Install dependencies
npm install

# Start development server with hot-reload
npm start

# Build for all platforms
npm run build

# Build for specific platform
npm run build:win    # Windows
npm run build:mac    # macOS
npm run build:linux  # Linux

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint
npm run lint:fix

zot-sn/
├── src/                      # TypeScript source code
│   ├── core/                 # Core sync engine
│   │   ├── sync-engine.ts
│   │   ├── file-monitor.ts
│   │   └── conflict-resolver.ts
│   ├── parsers/              # .mark file parsers
│   │   ├── mark-parser.ts
│   │   └── mark-to-zotero.ts
│   ├── exporters/            # Export/import logic
│   │   ├── pdf-exporter.ts
│   │   └── annotation-importer.ts
│   ├── ui/                   # User interface
│   │   ├── preferences.ts
│   │   ├── sync-dialog.ts
│   │   └── status-bar.ts
│   ├── types/                # TypeScript definitions
│   │   └── index.ts
│   └── index.ts              # Plugin entry point
├── addon/                    # Zotero addon resources
│   ├── locale/               # Localization files
│   ├── content/              # XUL/HTML content
│   └── skin/                 # CSS styles
├── parsers/                  # External parser binaries
├── docs/                     # Documentation
├── build/                    # Build output
├── test/                     # Test files
├── PLAN.md                   # Development plan
├── ARCHITECTURE.md           # Technical architecture
├── CHALLENGES.md             # Challenges and solutions
├── package.json              # NPM configuration
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

• PLAN.md - Complete development plan with phases and timeline
• ARCHITECTURE.md - Technical architecture and design
• CHALLENGES.md - Known challenges and mitigation strategies

This project is currently in early development. Contributions will be welcome once the core functionality is implemented.

Planned areas for contribution:

• Testing with different Supernote models
• Additional cloud storage backends (Dropbox, OneDrive)
• Localization (translations)
• Documentation improvements

• Basic PDF export
• Manual annotation import
• Configuration UI

• Automatic bidirectional sync
• Collection management
• Conflict detection and resolution
• Production-ready release

• Real-time sync with file watchers
• Support for additional cloud services
• Advanced annotation editing
• Sync profiles

• Direct cloud API integration
• Mobile companion app
• Collaboration features
• Advanced sync rules

AGPL-3.0-or-later

• Zotero team for the excellent reference manager
• Supernote team for the wonderful e-ink tablet
• SupernoteSharp and PySN-digest developers for reverse-engineering the .mark format
• ZotMoov for inspiration and proving the need for this workflow

• Author: btromm
• GitHub: https://github.com/btromm/zot-sn
• Issues: https://github.com/btromm/zot-sn/issues

• ✅ Project structure initialized
• ✅ Documentation complete (PLAN, ARCHITECTURE, CHALLENGES)
• ✅ TypeScript configuration set up
• ✅ Core placeholder files created
• 🚧 Beginning Phase 1 implementation

Note: This is an unofficial, community-developed plugin. It is not affiliated with or endorsed by Zotero or Supernote (Ratta).