brycewang-stanford/zotero-mdnotes-guide

Zotero MDNotes Guide

A skill for exporting Zotero items, annotations, and notes to structured Markdown files for use in knowledge management systems like Obsidian, Logseq, or plain Markdown workflows. Based on zotero-mdnotes (1K stars), this skill creates a bridge between your reference library and your personal knowledge base.

Overview

Zotero is excellent for managing references and reading PDFs, but its note-taking capabilities are limited compared to dedicated knowledge management tools. MDNotes solves this by exporting Zotero data to Markdown files that can be used in any Markdown-compatible system. Each exported file contains bibliographic metadata, your annotations, and your notes in a structured, interlinked format.

This approach gives researchers the best of both worlds: Zotero's powerful reference management with the flexibility and interconnection capabilities of Markdown-based knowledge systems.

Configuration

Template System

• MDNotes uses Nunjucks-based templates to control the output format
• Default templates produce well-structured Markdown with YAML frontmatter
• Templates can be customized to match your preferred note structure
• Separate templates exist for item metadata, annotations, and combined notes
• Template variables provide access to all Zotero metadata fields

Key Configuration Options

• Output directory: where exported Markdown files are saved
• File naming convention: citation key, title, or custom pattern
• Frontmatter fields: which metadata fields to include in YAML header
• Annotation grouping: by color, type, page, or section
• Link format: wiki-links, Markdown links, or plain text references

Frontmatter Configuration

• Title, authors, year, journal, DOI are standard frontmatter fields
• Tags from Zotero are converted to note tags
• Custom fields can be added (read status, rating, project association)
• Zotero item key is included for bidirectional linking
• Date fields use ISO 8601 format for consistent sorting

Export Workflows

Single Item Export

• Right-click a Zotero item and select the MDNotes export option
• Choose between metadata only, annotations only, or combined export
• The plugin generates the Markdown file in the configured output directory
• If a file with the same name exists, choose to overwrite or create a new version
• The exported file opens automatically in the configured editor (optional)

Batch Export

• Select multiple items or an entire collection in Zotero
• Apply export to the full selection
• Each item generates its own Markdown file
• A summary index file can optionally be generated listing all exported items
• Batch exports respect the same templates and configuration as single exports

Annotation Export

• PDF highlights are exported with their color, page number, and surrounding text
• Comments attached to highlights are included as sub-items
• Free-text notes from the Zotero note editor are exported as separate sections
• Annotations are grouped according to the configured strategy (color, page, etc.)
• Each annotation includes a link back to the specific PDF location in Zotero

Template Customization

Metadata Template

• Controls the structure of the bibliographic information section
• Standard fields: title, authors, year, journal, volume, pages, DOI, URL
• Extended fields: abstract, keywords, collection path, date added
• Custom fields: any Zotero extra field data
• The template determines the order and formatting of each field

Annotation Template

• Controls how individual annotations are formatted
• Color mapping: assign semantic meaning to highlight colors (yellow for key findings, blue for methodology, etc.)
• Include or exclude the page number, annotation date, and comment
• Format as blockquotes, bullet points, or plain text
• Group by color to create thematic sections automatically

Combined Template

• Merges metadata and annotations into a single cohesive note
• Includes section headings for clear structure
• Adds a personal notes section at the bottom for your own synthesis
• Includes a placeholder for connections to other notes
• Provides a reading status field for tracking progress

Knowledge Management Integration

Obsidian Integration

• Export to the Obsidian vault's literature notes folder
• Use wiki-link format for interoperability with Obsidian's linking system
• Tags are formatted as Obsidian-compatible hashtags
• Dataview-compatible frontmatter enables dynamic queries
• Graph view shows connections between literature notes and your other notes

Logseq Integration

• Export in Logseq-compatible Markdown format
• Use page references for linking between notes
• Properties block replaces YAML frontmatter for Logseq compatibility
• Block-level references are supported for granular linking
• Journal page references connect reading dates to daily notes

Plain Markdown Workflows

• Export to any directory for use with any Markdown editor
• Standard Markdown formatting ensures compatibility
• Frontmatter follows common conventions for static site generators
• Links use standard Markdown link syntax for maximum portability
• Files are self-contained with no external dependencies

Advanced Usage

Selective Field Export

• Configure which Zotero fields are exported to reduce noise
• Create focused templates for different project needs
• Academic fields: include abstract, methodology tags, dataset references
• Reading group fields: include discussion questions, presenter notes
• Writing project fields: include relevance score, key quotes, argument position

Incremental Updates

• Re-export items after adding new annotations
• The plugin can append new annotations or regenerate the full file
• Track changes between exports using version control
• Maintain a changelog of reading progress through dated annotations
• Sync exported files across devices using standard file sync tools

Custom Post-Processing

• Apply regex transformations to exported files
• Add custom metadata computed from Zotero fields
• Generate index files grouping exports by tag, year, or author
• Create citation graph files from the exported reference data
• Format exports for specific publishing pipelines

Integration with Research-Claw

This skill connects with the Research-Claw knowledge management workflow:

• Export Zotero annotations as the first step in building literature reviews
• Feed exported notes to synthesis and writing skills
• Connect with other citation skills for a complete reference workflow
• Use exported metadata for bibliometric analysis
• Store exported notes in the Research-Claw knowledge base for agent access

Best Practices

• Establish your template before exporting in bulk to avoid reformatting later
• Use a consistent color scheme for annotations across all papers
• Export promptly after reading to capture your fresh understanding
• Include a personal synthesis section in each literature note beyond just annotations
• Use tags consistently to enable useful filtering and grouping
• Back up both Zotero and the exported notes directory regularly