Cloudflare KV Sync

An Obsidian plugin that automatically syncs markdown files to Cloudflare KV storage based on Frontmatter configuration. Perfect for pulling content into a static site generator such as Eleventy, using Cloudflare KV as a bare bones CMS.

Features

• Automatic syncing: Files marked with a sync flag automatically upload when modified
• Auto-generated IDs: Unique document IDs are automatically assigned when missing
• Duplicate detection: Detects and auto-corrects duplicate KV keys during full sync
• Collection support: Organize KV keys with optional collection prefixes
• Smart key management: Handles collection changes and removes old keys automatically
• Error log: Errors are logged to a persistent file in your vault root
• Manual controls: Ribbon icon and commands for manual operations
• Configurable: Customize sync keys, ID fields, and sync behavior
• Debounced uploads: Prevents excessive API calls during rapid editing

Installation

From Obsidian Community Plugins (Recommended)

1. Open Obsidian Settings
2. Go to Community Plugins and disable Safe Mode
3. Click Browse and search for "Cloudflare KV Sync"
4. Install and enable the plugin

Manual Installation

1. Download the latest release from GitHub
2. Extract the files to your vault's .obsidian/plugins/cloudflare-kv-sync/ folder
3. Enable the plugin in Obsidian settings

Development Installation

1. Clone this repository
2. Run pnpm install to install dependencies
3. Run pnpm run build to build the plugin
4. Copy main.js, manifest.json, and versions.json to a new folder in your vault's plugin folder, eg. .obsidian/plugins/cloudflare-kv-sync/

Setup

1. Cloudflare Configuration

1. Create a Cloudflare KV namespace in your dashboard
   • Note the namespace ID
2. Create an API token with these permissions:
   • Account: Workers KV Storage:Edit
3. Note your Account ID

2. Plugin Configuration

1. Go to Settings → Community Plugins → Cloudflare KV Sync
2. Enter your:
   • Account ID: Cloudflare Dashboard → three dots to right of account name → Copy account ID
   • Namespace ID: Found in Storage & Databases → KV → Your namespace
   • API Token: The token you created above
3. Configure optional settings:
   • Sync Key: Frontmatter key to check for sync flag (default: kv_sync)
   • ID Key: Frontmatter key containing document ID (default: id)
   • Auto-sync: Enable/disable automatic syncing on file changes

Usage

Basic Syncing

Add the sync flag to your markdown frontmatter. A unique ID will be automatically generated if you don't provide one:

---
kv_sync: true
title: My Amazing Post
---
Your content here...

The plugin will auto-generate an id field (a UUID) and sync the file to KV.

You can also set your own ID manually — it will be preserved as-is:

---
id: my-unique-post-id
kv_sync: true
title: My Amazing Post
---
Your content here...

The file will sync to KV with key: my-unique-post-id

Collection Organization

Use collections to organize your KV keys:

---
id: my-blog-post
kv_sync: true
collection: writing
title: My Blog Post
---

This creates KV key: writing/my-blog-post

Manual Controls

• Ribbon icon: Click the cloud upload icon to sync all marked files.
• Command palette:
  • "Sync current file to Cloudflare KV"
  • "Sync all marked files to Cloudflare KV"

Sync Behavior

• Enable sync: Set kv_sync: true in frontmatter.
• Disable sync: Set kv_sync to any value other than true or remove the key entirely.
• Change collection: Update the collection value. Old keys are automatically removed.
• Auto-cleanup: Removing sync flag automatically removes the file from KV.

Configuration Options

Examples

Simple Blog Post (auto-generated ID)

---
kv_sync: true
title: Hello World
date: 2024-01-15
---
# Hello World
This is my first post!

KV Key: auto-generated UUID (e.g. a1b2c3d4-e5f6-7890-abcd-ef1234567890)

Blog Post with Manual ID

---
id: hello-world
kv_sync: true
title: Hello World
date: 2024-01-15
---
# Hello World
This is my first post!

KV Key: hello-world

Organized Content

---
id: advanced-js-patterns
kv_sync: true
collection: tutorials
title: Advanced JavaScript Patterns
tags: [javascript, programming]
---
# Advanced JavaScript Patterns
Learn about advanced patterns...

KV Key: tutorials/advanced-js-patterns

Draft Content (Not Synced)

---
id: work-in-progress
kv_sync: false
title: Work in Progress
---
This won't be synced to KV.

Troubleshooting

Common Issues

• Files not syncing: Check that kv_sync: true exists in frontmatter (an id will be auto-generated if missing)
• API errors: Verify your Account ID, Namespace ID, and API token
• Permission errors: Ensure API token has Cloudflare Workers:Edit permission
• Old keys remaining: Plugin automatically cleans up when collections change
• Duplicate IDs: The plugin detects duplicate KV keys during full sync and auto-assigns new IDs to resolve conflicts

Debug Steps

1. Check the Cloudflare KV Sync error log.md file in your vault root for error details
2. Verify Cloudflare KV namespace exists and is accessible
3. Test API token permissions in Cloudflare dashboard
4. Ensure frontmatter is valid YAML syntax

Development

Building

pnpm install
pnpm run build

Development Mode

pnpm run dev

This will watch for changes and rebuild automatically.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions or share use cases

Changelog

0.1.0

• Initial release
• Automatic KV syncing based on frontmatter flags
• Collection support for organized keys
• Smart key management and cleanup
• Configurable sync behavior