quicknotes/specs/emacs_integration.md

# Emacs Integration Specification

## Overview

QuickNotes provides an Emacs mode that allows users to access and interact with the application directly from Emacs. This integration enables viewing feeds, readlist items, and notes without leaving the editor.

## Features

### Core Functionality

1. **View Feed Entries**: Browse entries from RSS/Atom feeds
2. **Browse Readlist**: Access saved read-later items
3. **Navigate Notes**: Browse and search through notes
4. **View Content**: Read feed entries, readlist items, and notes
5. **Mark as Read**: Mark items as read/unread
6. **HTML to Org Conversion**: Convert HTML content to Org mode format

### Navigation

1. **List Views**: Display lists of feeds, readlist items, and notes
2. **Item View**: Display the content of a selected item
3. **Back Navigation**: Return to previous views
4. **Refresh**: Update content from the server

### Content Rendering

1. **HTML Rendering**: Display HTML content in Emacs
2. **Org Mode Conversion**: Convert HTML to Org mode format using Pandoc
3. **Syntax Highlighting**: Apply appropriate syntax highlighting to code blocks
4. **Link Handling**: Make links clickable and functional

## Implementation

### Dependencies

1. **request.el**: For API communication
2. **markdown-mode**: For rendering Markdown content
3. **pandoc**: For converting HTML to Org mode format (optional)

### Configuration

```elisp
;; Set the API URL
(setq quicknotes-api-url "http://localhost:3000/api")

;; Enable Pandoc conversion to Org mode
(setq quicknotes-use-pandoc t)
```

### Key Bindings

| Key | Function | Description |
|-----|----------|-------------|
| `RET` | `quicknotes-open-item` | Open the item at point |
| `r` | `quicknotes-mark-read` | Mark the item as read |
| `f` | `quicknotes-list-feeds` | List feed entries |
| `l` | `quicknotes-list-readlist` | List read later items |
| `n` | `quicknotes-list-notes` | List notes |
| `o` | `quicknotes-toggle-org` | Toggle between HTML and Org mode rendering |
| `g` | `quicknotes-refresh` | Refresh the current buffer |
| `q` | `quicknotes-quit` | Quit the current buffer |

### Buffer Types

1. **Feeds List Buffer**: Displays a list of feed entries
2. **Readlist Buffer**: Displays a list of read later items
3. **Notes List Buffer**: Displays a list of notes
4. **Content Buffer**: Displays the content of a selected item

## API Integration

### API Endpoints Used

1. **GET /api/feeds/entries**: Fetch feed entries
2. **GET /api/readlist**: Fetch read later items
3. **GET /api/notes**: Fetch notes
4. **GET /api/feeds/entries/:id**: Fetch a specific feed entry
5. **GET /api/readlist/:id**: Fetch a specific read later item
6. **GET /api/notes/:id**: Fetch a specific note
7. **PUT /api/feeds/entries/:id/read**: Mark a feed entry as read
8. **PUT /api/readlist/:id/read**: Mark a read later item as read

### Authentication

The Emacs mode does not currently implement authentication, as the QuickNotes API is designed for local use without authentication.

## User Interface

### List View

```
QuickNotes - Feeds

[2023-01-01] Title of Feed Entry 1
[2023-01-02] Title of Feed Entry 2
[2023-01-03] Title of Feed Entry 3

Press 'f' for feeds, 'l' for readlist, 'n' for notes, 'q' to quit
```

### Content View

```
Title: Example Article

This is the content of the article, rendered in Emacs.

Links are clickable, and code blocks have syntax highlighting.

Press 'r' to mark as read, 'o' to toggle Org mode, 'q' to return to list
```

## HTML to Org Conversion

The Emacs mode can convert HTML content to Org mode format using Pandoc:

```elisp
(defun quicknotes-html-to-org (html)
  "Convert HTML to Org mode format using Pandoc."
  (when (and quicknotes-use-pandoc (executable-find "pandoc"))
    (with-temp-buffer
      (insert html)
      (shell-command-on-region (point-min) (point-max)
                               "pandoc -f html -t org"
                               (current-buffer) t)
      (buffer-string))))
```

## Error Handling

1. **Connection Errors**: Display a message when the API is unreachable
2. **Not Found Errors**: Handle 404 responses gracefully
3. **Server Errors**: Display error messages from the server
4. **Pandoc Errors**: Fall back to HTML rendering if Pandoc conversion fails

## Future Enhancements

1. **Create/Edit Notes**: Allow creating and editing notes from Emacs
2. **Save to Readlist**: Add the ability to save URLs to the readlist
3. **Subscribe to Feeds**: Add the ability to subscribe to new feeds
4. **Search**: Implement search functionality across all content types
5. **Offline Mode**: Cache content for offline access
6. **Customizable Faces**: Allow customizing the appearance of different elements