# Obsidian Cloudflare KV Sync

[![CI](https://github.com/alexmensch/obsidian-cloudflare-kv-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/alexmensch/obsidian-cloudflare-kv-sync/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/alexmensch/obsidian-cloudflare-kv-sync/graph/badge.svg)](https://codecov.io/gh/alexmensch/obsidian-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:

```yaml
---
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:

```yaml
---
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:

```yaml
---
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

| Setting        | Default   | Description                                                      |
| -------------- | --------- | ---------------------------------------------------------------- |
| Sync Key       | `kv_sync` | Frontmatter key to check for sync flag                           |
| ID Key         | `id`      | Frontmatter key containing document ID (auto-generated if empty) |
| Auto-sync      | `false`   | Automatically sync files on modification                         |
| Debounce Delay | `60s`     | Wait time before syncing after file changes                      |

## Examples

### Simple Blog Post (auto-generated ID)

```yaml
---
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

```yaml
---
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

```yaml
---
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)

```yaml
---
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

```bash
pnpm install
pnpm run build
```

### Development Mode

```bash
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