A Python library to retrieve annotations and notes from Zotero and save them into Markdown files.

Overview

Zotero to Markdown

Generate Markdown files from Zotero annotations and notes. With new Zotero PDF Reader, all highlights are saved in the Zotero database. The highlights are NOT saved in the PDF file unless you export the highlights in order to save them.

If you annotate your files outside the new Zotero PDF reader, this library will not work with your PDF annotations as those are not retrievable from Zotero API. In that case, you may want to use zotfile + mdnotes to extract the annotations and convert them into markdown files.

This library is for you if you annotate (highlight + note) using the Zotero's PDF reader (including the Zotero iOS)

Installation

You can install the library by running

pip install zotero2md

Note: If you do not have pip installed on your system, you can follow the instructions here.

Usage

Since we have to retrieve the notes from Zotero API, the minimum requirements are:

  • Zotero API key [Required]: Create a new Zotero Key from your Zotero settings
  • Zotero personal or group ID [Required]:
    • Your personal library ID (aka userID) can be found here next to Your userID for use in API calls is XXXXXX.
    • If you're using a group library, you can find the library ID by
      1. Go to https://www.zotero.org/groups/
      2. Click on the interested group.
      3. You can find the library ID from the URL link that has format like https://www.zotero.org/groups/<group_id>/group_name. The number between /groups/ and /group_name is the libarry ID.
  • Zotero library type [Optional]: "user" (default) if using personal library and "group" if using group library.

Note that if you want to retrieve annotations and notes from a group, you should provide the group ID (zotero_library_id=<group_id>) and set the library type to group (zotero_library_type="group").

Approach 1 (Recommended)

After installing the library, open a Python terminal, and then execute the following:

from zotero2md.zt2md import Zotero2Markdown

zt = Zotero2Markdown(
    zotero_key="your_zotero_key",  
    zotero_library_id="your_zotero_id", 
    zotero_library_type="user", # "user" (default) or "group"
    params_filepath="",  # [Default values provided bellow] # The path to JSON file containing the custom parameters (See Section Custom Output Parameters).
    include_annotations=True, # Default: True
    include_notes=True, # Default: True
)
zt.run_all()

Just to make sure that all files are created, you can run save_failed_items_to_txt() to ensure that no file was was failed to create. If a file or more failed to create, the filename (item title) and the corresponding Zotero item key will be saved to a txt file.

zt.save_failed_items_to_txt("failed_zotero_items.txt")

Approach 2

For this approach, you need to download output_to_md.py script. Run python output_to_md.py -h to get more information about all options.

python zotero2md/output_to_md.py <zotero_key> <zotero_id>

For instance, assuming zotero_key=abcd and zotero_id=1234, you can simply run the following:

python zotero2md/output_to_md.py abcd 1234

Custom Output Parameters

You can change default parameters by passing the --config_filepath option with the path to a JSON file containing the desired configurations. For instance,

python zotero2md/generate.py <zotero_key> <zotero_id> --config_filepath ./sample_params.json
Parameter type default value
convertTagsToInternalLinks bool true
doNotConvertFollowingTagsToLink List of strings [ ]
includeHighlightDate bool true
hideHighlightDateInPreview bool true

Any parameter in the JSON file will override the default setting. If a parameter is not provided, then the default value will be used.

For example, if you don't want to show the highlight date in the output file, you can simply pass a JSON file with the following content:

{
  "hideHighlightDateInPreview": false
}

Features

  • Generate MD files for all annotations and notes saved in Zotero
  • The ability to convert Zotero tags to internal links ([[ ]]) used in many bidirectional MD editors.
    • You can even pass certain tags that you don't want to convert to internal links! (using doNotConvertFollowingTagsToLink parameter)

Quick note

Since I'm personally using Obsidian as my markdown editor, there are custom parameters to generate MD files that are consistent with Obsidian and I'm planning to add more option there.

Roadmap

  • Update existing annotations and notes
  • Option to add frontmatter section (particularly useful for Obsidian)
  • More flexibility in styling the output files

Request a new feature or report a bug

Feel free to request a new feature or report a bug in GitHub issue here.

📫 How to reach me:

Personal Website LinkedIn Medium Twitter

Buy Me A Coffee

You might also like...
A Python implementation of John Gruber’s Markdown with Extension support.

Python-Markdown This is a Python implementation of John Gruber's Markdown. It is almost completely compliant with the reference implementation, though

A Python implementation of John Gruber’s Markdown with Extension support.

Python-Markdown This is a Python implementation of John Gruber's Markdown. It is almost completely compliant with the reference implementation, though

Extensions for Python Markdown

PyMdown Extensions Extensions for Python Markdown. Documentation Extension documentation is found here: https://facelessuser.github.io/pymdown-extensi

Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed. Now in Python!

markdown-it-py Markdown parser done right. Follows the CommonMark spec for baseline parsing Configurable syntax: you can add new rules and even replac

Lightweight Markdown dialect for Python desktop apps
Lightweight Markdown dialect for Python desktop apps

Litemark is a lightweight Markdown dialect originally created to be the markup language for the Codegame Platform project. When you run litemark from the command line interface without any arguments, the Litemark Viewer opens and displays the rendered demo.

A markdown template manager for writing API docs in python.

DocsGen-py A markdown template manager for writing API docs in python. Contents Usage API Reference Usage You can install the latest commit of this re

Livemark is a static page generator that extends Markdown with interactive charts, tables, and more.

Livermark This software is in the early stages and is not well-tested Livemark is a static site generator that extends Markdown with interactive chart

Read a list in markdown and do something with it!

Markdown List Reader A simple tool for reading lists in markdown. Usage Begin by running the mdr.py file and input either a markdown string with the -

Yuque2md - Offline download the markdown file and image from yuque

yuque2md 按照语雀知识库里的目录,导出语雀知识库中所有的markdown文档,并离线图片到本地 使用 安装 Python3.x clone 项目 下载依

Comments
  • feat: Add notes to the output. Use markdownify library to convert HTM…

    feat: Add notes to the output. Use markdownify library to convert HTM…

    …L-styled notes to markdown.

    Rename user_id argument to library_id. Rename group_annotations_by_parent_file() to group_by_parent_item(). Minor refactoring.

    opened by e-alizadeh 0
  • Custom export directory

    Custom export directory

    I export directly to my python parent folder. However is it possible to redefine the export directory? So I can directly save to relevant folder in Obsidian. Thank you!

    opened by schanzerman 1
  • Key error when retriving annotations

    Key error when retriving annotations

    I executed this package in Python 3.9 using the Approach 1. Unfortunately, there are some errors when I tried to execute.

    from zotero2md.zt2md import Zotero2Markdown
    
    zt = Zotero2Markdown(
        zotero_key="xxx",  
        zotero_library_id="xxx", 
        zotero_library_type="user", # "user" (default) or "group"
        params_filepath="./sample_params.json",  # [Default values provided bellow] # The path to JSON file containing the custom parameters (See Section Custom Output Parameters).
        include_annotations=True, # Default: True
        include_notes=True, # Default: True
    )
    zt.run_all()
    

    The result is:

    ---------------------------------------------------------------------------
    KeyError                                  Traceback (most recent call last)
    ~\AppData\Local\Temp/ipykernel_14832/1010544329.py in <module>
          9     include_notes=True, # Default: True
         10 )
    ---> 11 zt.run_all()
    
    ~\anaconda3\envs\zotero\lib\site-packages\zotero2md\zt2md.py in run_all(self, params_filepath)
         39             )
         40         if self.include_notes:
    ---> 41             notes_grouped = group_by_parent_item(retrieve_all_notes(self.zotero_client))
         42 
         43         for i, item_key in enumerate(annots_grouped.keys()):
    
    ~\anaconda3\envs\zotero\lib\site-packages\zotero2md\utils.py in group_by_parent_item(annotations)
          6     annotations_by_parent = defaultdict(list)
          7     for annot in annotations:
    ----> 8         annotations_by_parent[annot["data"]["parentItem"]].append(annot)
          9     return annotations_by_parent
         10 
    
    KeyError: 'parentItem'
    

    Is this problem a bug?

    opened by mildwall 3
Releases(v0.2.0)
Owner
Essi Alizadeh
Engineer & Data Scientist in Permanent Beta: Learning, Improving, Evolving ...
Essi Alizadeh
A markdown lexer and parser which gives the programmer atomic control over markdown parsing to html.

A markdown lexer and parser which gives the programmer atomic control over markdown parsing to html.

stonepresto 4 Aug 13, 2022
A command line tool that can convert Day One data into markdown files.

Introduction Features Before Start Export data from Day One Check Integrity Special Cases for Photo Extension Name Audio Extension Name Usage Known Is

gyro永不抽风 26 Dec 31, 2022
Converts a grading Excel sheet into Markdown documents.

GradeDocs Turns Excel worksheets into grade/score documents. Example Given such an Excel Worksheet (see examples/example.xlsx): The following commands

Patrick Bucher 1 Dec 19, 2021
A super simple script which uses the GitHub API to convert your markdown files to GitHub styled HTML site.

A super simple script which uses the GitHub API to convert your markdown files to GitHub styled HTML site.

Çalgan Aygün 213 Dec 22, 2022
Preview GitHub README.md files locally before committing them.

Grip -- GitHub Readme Instant Preview Render local readme files before sending off to GitHub. Grip is a command-line server application written in Pyt

Joe Esposito 5.9k Jan 8, 2023
A fast yet powerful Python Markdown parser with renderers and plugins.

Mistune v2 A fast yet powerful Python Markdown parser with renderers and plugins. NOTE: This is the re-designed v2 of mistune. Check v1 branch for ear

Hsiaoming Yang 2.2k Jan 4, 2023
Static site generator that supports Markdown and reST syntax. Powered by Python.

Pelican Pelican is a static site generator, written in Python. Write content in reStructuredText or Markdown using your editor of choice Includes a si

Pelican dev team 11.3k Jan 5, 2023
markdown2: A fast and complete implementation of Markdown in Python

Markdown is a light text markup format and a processor to convert that to HTML. The originator describes it as follows: Markdown is a text-to-HTML con

Trent Mick 2.4k Dec 30, 2022
A fast, extensible and spec-compliant Markdown parser in pure Python.

mistletoe mistletoe is a Markdown parser in pure Python, designed to be fast, spec-compliant and fully customizable. Apart from being the fastest Comm

Mi Yu 546 Jan 1, 2023
A lightweight and fast-to-use Markdown document generator based on Python

A lightweight and fast-to-use Markdown document generator based on Python

快乐的老鼠宝宝 1 Jan 10, 2022