raindropmd 0.1.0

Raindrop.io CSV to Zettelkasten Markdown CLI

Raindrop.io CSV to Zettelkasten-based Markdown

A Python CLI tool to parse a CSV export from Raindrop.io and create a directory of individual markdown files - one per bookmark - using Zettelkasten-style filenames.

Table of Contents

• Features
• Requirements
• Installation
• Usage
• Template
• Future Enhancements
• License

Features

• Parses Raindrop.io CSV exports
• Extracts bookmarks and highlights
• Creates a directory of markdown files (one per bookmark)
• Zettelkasten-style filenames: {YYYYMMDDHHMM}_{title}.md
• Interactive CLI to show, edit, remove, and search bookmarks in the directory
• Fuzzy search across all bookmarks
• Robust error handling and logging
• Comprehensive unit tests

Requirements

• Python 3.8+

Installation

1. Clone the repository:

   git clone <repository-url>
   

2. Navigate to the project directory

   cd <project-directory>
   

3. (Optional) Create and activate a virtual environment

   python -m venv venv
   source venv/bin/activate # On Windows, use `venv\Scripts\activate`
   

Usage

1. Place your Raindrop.io CSV export anywhere on your system.
2. Run the script to create a directory of markdown files:

   python raindropMD.py create <your_csv_file.csv> <output_directory>
   

   Example:

   python raindropMD.py create ~/Downloads/raindrop.csv bookmarks/
   

3. Use the CLI to manage your bookmarks:
   • List all bookmarks:

     python raindropMD.py list <output_directory>
     

   • Edit a bookmark interactively:

     python raindropMD.py edit <output_directory>
     

   • Remove a bookmark interactively:

     python raindropMD.py remove <output_directory>
     

   • Fuzzy search bookmarks:

     python raindropMD.py search <output_directory> <query>
     

Template System

This tool supports user-editable markdown templates for generating bookmark notes. Templates are written using the Jinja2 templating language and must follow these conventions:

Template File Requirements

• Templates must be placed in the templates/ directory and have the .md.j2 extension (e.g., bookmark_template.md.j2).
• The template filename is used as its identifier and is referenced in the YAML frontmatter of each generated note.

Template Syntax

• Use Jinja2 variable syntax for bookmark fields, e.g. {{ title }}, {{ url }}, {{ tags }}.
• Standard bookmark fields available:
  • title, url, cover, tags, created, favorite, excerpt, note, highlights
• You may define additional user sections by adding new variables (e.g., {{ user_notes }}) in the template. These will be preserved and editable in the CLI.
• To render highlights as a list, use a Jinja2 loop:

  {% if highlights %}
  ### Highlights:
  {% for h in highlights %}
  > {{ h }}
  {% endfor %}
  {% endif %}
  

• You can use any valid Jinja2 syntax for formatting, conditionals, and loops.

YAML Frontmatter

• Each generated note includes YAML frontmatter indicating the template used:

  ---
  template: bookmark_template.md.j2
  ---
  

• The tool uses this field to ensure the correct template is used for editing and parsing.

Example Template

## [{{ title }}]({{ url }})
{% if cover %}![cover image]({{ cover }}){% endif %}
**Tags:** {{ tags }}
**Created:** {{ created }}
{% if favorite %}⭐ **Favorite**{% endif %}
{% if excerpt %}
_Excerpt:_ {{ excerpt }}
{% endif %}
{% if note %}
_Note:_ {{ note }}
{% endif %}
{% if highlights %}
### Highlights:
{% for h in highlights %}
> {{ h }}
{% endfor %}
{% endif %}

User-Defined Sections

• Any variable in the template that is not a standard bookmark field is treated as a user-defined section (e.g., {{ user_notes }}).
• The CLI will prompt for these sections when creating or editing notes, and will preserve their content on update.

Template Best Practices

• Use clear section headers (e.g., ### Notes) for user-defined sections.
• Avoid duplicate variable names.
• Test your template with a sample bookmark to ensure all fields render as expected.

See the templates/ directory for working examples.

TODOs

• Improve CLI output
• Add markdown template customization
• Improve bookmark editing
• Add note title customization
• Add GitHub Action to create, test, and publish package
• Add Raindrop API use to automate CSV export

License

This project is licensed under the MIT License.