markdown-notes-engine 1.0.0

package/README.md

@@ -0,0 +1,196 @@
+# Markdown Notes Engine
+
+[![npm version](https://img.shields.io/npm/v/markdown-notes-engine.svg)](https://www.npmjs.com/package/markdown-notes-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A complete, production-ready markdown note-taking engine with GitHub integration and media hosting. Add powerful note-taking capabilities to any Node.js application with just a few lines of code.
+
+## Features
+
+- **Full Markdown Support** - Rich markdown editing with live preview
+- **GitHub Integration** - Automatic version control for all notes
+- **Media Hosting** - Image and video uploads to Cloudflare R2 or AWS S3
+- **Syntax Highlighting** - Beautiful code blocks with highlight.js
+- **Auto-save** - Never lose your work with automatic saving
+- **Search** - Full-text search across all notes
+- **Dark Mode** - Built-in dark mode support
+- **Responsive** - Works beautifully on mobile and desktop
+- **Keyboard Shortcuts** - Boost productivity with keyboard shortcuts
+- **Drag & Drop** - Upload media with drag and drop
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install markdown-notes-engine
+```
+
+### Backend (Express)
+
+```javascript
+const { createNotesRouter } = require('markdown-notes-engine');
+
+const notesRouter = createNotesRouter({
+  github: {
+    token: process.env.GITHUB_TOKEN,
+    owner: process.env.GITHUB_OWNER,
+    repo: process.env.GITHUB_REPO
+  },
+  storage: {
+    type: 'r2',
+    accountId: process.env.R2_ACCOUNT_ID,
+    accessKeyId: process.env.R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+    bucketName: process.env.R2_BUCKET_NAME,
+    publicUrl: process.env.R2_PUBLIC_URL
+  }
+});
+
+app.use('/api', notesRouter);
+```
+
+### Frontend (JavaScript)
+
+```html
+<div id="notes-app"></div>
+
+<script src="node_modules/markdown-notes-engine/lib/frontend/index.js"></script>
+<script>
+  const editor = new NotesEditor({
+    container: '#notes-app',
+    apiEndpoint: '/api'
+  });
+</script>
+```
+
+## Documentation
+
+For complete documentation, see:
+- **[Full Documentation](lib/README.md)** - Complete API reference and usage guide
+- **[Express Example](examples/express-app/README.md)** - Working Express.js integration example
+
+## Examples
+
+Check out the `/examples` directory for complete working examples:
+
+- **Express App** - Full Express.js integration with frontend
+- More examples coming soon!
+
+## Architecture
+
+The package provides:
+
+### Backend
+- **`createNotesRouter(config)`** - Express router with all API endpoints
+- **`GitHubClient`** - GitHub API wrapper for note storage
+- **`StorageClient`** - R2/S3 client for media uploads
+- **`MarkdownRenderer`** - Markdown to HTML renderer with syntax highlighting
+
+### Frontend
+- **`NotesEditor`** - Complete note-taking UI component
+- **Styles** - Beautiful, customizable styles with dark mode
+
+## Requirements
+
+- Node.js >= 16.0.0
+- GitHub personal access token with `repo` scope
+- Cloudflare R2 or AWS S3 account (for media uploads)
+
+## Environment Variables
+
+```env
+GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+GITHUB_OWNER=your-username
+GITHUB_REPO=your-notes-repo
+
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=your-access-key
+R2_SECRET_ACCESS_KEY=your-secret-key
+R2_BUCKET_NAME=your-bucket
+R2_PUBLIC_URL=https://your-bucket.r2.dev
+```
+
+## Development
+
+This repository contains both the package source and a working notes application.
+
+### Project Structure
+
+```
+markdown-notes-engine/
+├── lib/                    # NPM package source
+│   ├── backend/           # Express router and API
+│   ├── frontend/          # Editor UI component
+│   └── index.js           # Main package entry
+├── examples/              # Usage examples
+│   └── express-app/       # Express integration example
+├── server.js              # Demo server
+├── public/                # Demo frontend
+└── package.json           # Package configuration
+```
+
+### Running the Demo
+
+```bash
+# Install dependencies
+npm install
+
+# Create .env file with your credentials
+cp .env.example .env
+
+# Start the server
+npm run dev
+```
+
+Open `http://localhost:3001` to see the demo application.
+
+## API Endpoints
+
+When mounted, the notes router provides:
+
+- `GET /structure` - Get file tree
+- `GET /note` - Get note content
+- `POST /note` - Save note
+- `DELETE /note` - Delete note
+- `POST /folder` - Create folder
+- `DELETE /folder` - Delete folder
+- `POST /upload-image` - Upload image
+- `POST /upload-video` - Upload video
+- `POST /render` - Render markdown
+- `GET /search` - Search notes
+
+## Keyboard Shortcuts
+
+- `Ctrl/Cmd + S` - Save note
+- `Ctrl/Cmd + P` - Toggle preview
+- `Ctrl/Cmd + N` - New note
+- `Ctrl/Cmd + U` - Upload image
+- `Ctrl/Cmd + Shift + U` - Upload video
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details
+
+## Support
+
+- 📖 [Documentation](lib/README.md)
+- 💬 [Issues](https://github.com/cdthomp1/notes/issues)
+- 📧 [Contact](mailto:your-email@example.com)
+
+## Acknowledgments
+
+Built with:
+- [Express](https://expressjs.com/) - Web framework
+- [Marked](https://marked.js.org/) - Markdown parser
+- [Highlight.js](https://highlightjs.org/) - Syntax highlighting
+- [Octokit](https://github.com/octokit/rest.js/) - GitHub API client
+- [AWS SDK](https://aws.amazon.com/sdk-for-javascript/) - S3/R2 client
+
+---
+
+Made with ❤️ for markdown lovers everywhere

package/lib/README.md

@@ -0,0 +1,312 @@
+# Markdown Notes Engine
+
+A complete, production-ready markdown note-taking engine with GitHub integration and media hosting. Add powerful note-taking capabilities to any Node.js application with just a few lines of code.
+
+## Features
+
+- **Full Markdown Support**: Rich markdown editing with live preview
+- **GitHub Integration**: Automatic version control - all notes saved to GitHub
+- **Media Hosting**: Image and video uploads to Cloudflare R2 or AWS S3
+- **Syntax Highlighting**: Beautiful code blocks with highlight.js
+- **Auto-save**: Automatic note saving with configurable debounce
+- **Search**: Full-text search across all notes
+- **Dark Mode**: Built-in dark mode support
+- **Responsive**: Mobile-friendly UI
+- **Keyboard Shortcuts**: Productivity-focused shortcuts
+- **Drag & Drop**: Drag and drop images/videos directly into the editor
+
+## Installation
+
+```bash
+npm install markdown-notes-engine
+```
+
+## Quick Start
+
+### Backend Setup (Express)
+
+```javascript
+const express = require('express');
+const { createNotesRouter } = require('markdown-notes-engine');
+
+const app = express();
+
+// Create the notes router with your configuration
+const notesRouter = createNotesRouter({
+  github: {
+    token: process.env.GITHUB_TOKEN,
+    owner: process.env.GITHUB_OWNER,
+    repo: process.env.GITHUB_REPO
+  },
+  storage: {
+    type: 'r2', // or 's3'
+    accountId: process.env.R2_ACCOUNT_ID,
+    accessKeyId: process.env.R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+    bucketName: process.env.R2_BUCKET_NAME,
+    publicUrl: process.env.R2_PUBLIC_URL
+  },
+  options: {
+    autoUpdateReadme: true // Auto-update README with note index
+  }
+});
+
+// Mount the router
+app.use('/api', notesRouter);
+
+app.listen(3000, () => {
+  console.log('Notes app running on http://localhost:3000');
+});
+```
+
+### Frontend Setup (HTML + JavaScript)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>My Notes App</title>
+  <!-- Include the styles -->
+  <link rel="stylesheet" href="node_modules/markdown-notes-engine/lib/frontend/styles.css">
+</head>
+<body>
+  <div id="notes-app"></div>
+
+  <!-- Include the frontend module -->
+  <script src="node_modules/markdown-notes-engine/lib/frontend/index.js"></script>
+  <script>
+    // Initialize the editor
+    const editor = new NotesEditor({
+      container: '#notes-app',
+      apiEndpoint: '/api',
+      theme: 'light', // or 'dark'
+      autoSave: true,
+      autoSaveDelay: 2000
+    });
+  </script>
+</body>
+</html>
+```
+
+## Configuration
+
+### Backend Configuration
+
+#### GitHub Settings
+
+```javascript
+github: {
+  token: 'ghp_xxxxxxxxxxxx',     // GitHub personal access token
+  owner: 'your-username',         // Repository owner
+  repo: 'your-notes-repo'         // Repository name
+}
+```
+
+**Required GitHub Token Permissions:**
+- `repo` (Full control of private repositories)
+
+#### Storage Settings (Cloudflare R2)
+
+```javascript
+storage: {
+  type: 'r2',
+  accountId: 'your-account-id',
+  accessKeyId: 'your-access-key',
+  secretAccessKey: 'your-secret-key',
+  bucketName: 'your-bucket-name',
+  publicUrl: 'https://your-bucket.r2.dev'
+}
+```
+
+#### Storage Settings (AWS S3)
+
+```javascript
+storage: {
+  type: 's3',
+  region: 'us-east-1',
+  accessKeyId: 'your-access-key',
+  secretAccessKey: 'your-secret-key',
+  bucketName: 'your-bucket-name',
+  publicUrl: 'https://your-bucket.s3.amazonaws.com'
+}
+```
+
+#### Options
+
+```javascript
+options: {
+  autoUpdateReadme: true  // Automatically update README.md with note index
+}
+```
+
+### Frontend Configuration
+
+```javascript
+const editor = new NotesEditor({
+  container: '#notes-app',        // CSS selector for container element
+  apiEndpoint: '/api',            // API endpoint (where backend is mounted)
+  theme: 'light',                 // 'light' or 'dark'
+  autoSave: true,                 // Enable auto-save
+  autoSaveDelay: 2000,            // Auto-save delay in milliseconds
+  onSave: (path, content) => {},  // Callback when note is saved
+  onLoad: (path, content) => {},  // Callback when note is loaded
+  onError: (message, error) => {} // Error callback
+});
+```
+
+## API Endpoints
+
+When you mount the notes router, it provides these endpoints:
+
+### Notes Management
+- `GET /structure` - Get file tree structure
+- `GET /note?path={path}` - Get note content
+- `POST /note` - Save/create note
+- `DELETE /note` - Delete note
+- `POST /folder` - Create folder
+- `DELETE /folder` - Delete folder
+
+### Media Upload
+- `POST /upload-image` - Upload image (multipart)
+- `POST /upload-image-base64` - Upload image (base64)
+- `POST /upload-video` - Upload video
+- `DELETE /image` - Delete image
+- `DELETE /video` - Delete video
+
+### Utilities
+- `POST /render` - Render markdown to HTML
+- `GET /search?q={query}` - Search notes
+
+## Keyboard Shortcuts
+
+- `Ctrl/Cmd + S` - Save note
+- `Ctrl/Cmd + P` - Toggle preview mode
+- `Ctrl/Cmd + N` - Create new note
+- `Ctrl/Cmd + U` - Upload image
+- `Ctrl/Cmd + Shift + U` - Upload video
+- `Esc` - Close modals
+
+## Advanced Usage
+
+### Using Individual Components
+
+You can use individual backend components if you need more control:
+
+```javascript
+const { GitHubClient, StorageClient, MarkdownRenderer } = require('markdown-notes-engine');
+
+// GitHub client
+const github = new GitHubClient({
+  token: 'xxx',
+  owner: 'user',
+  repo: 'repo'
+});
+
+// Get file structure
+const structure = await github.getFileStructure();
+
+// Get file content
+const file = await github.getFile('path/to/note.md');
+
+// Save file
+await github.saveFile('path/to/note.md', 'content', file.sha);
+
+// Storage client
+const storage = new StorageClient({
+  type: 'r2',
+  accountId: 'xxx',
+  accessKeyId: 'xxx',
+  secretAccessKey: 'xxx',
+  bucketName: 'bucket',
+  publicUrl: 'https://bucket.r2.dev'
+});
+
+// Upload image
+const imageUrl = await storage.uploadImage(buffer, 'image.png', 'folder');
+
+// Markdown renderer
+const renderer = new MarkdownRenderer();
+const html = renderer.render('# Hello World');
+```
+
+### Frontend Callbacks
+
+Use callbacks to integrate with your application:
+
+```javascript
+const editor = new NotesEditor({
+  container: '#notes-app',
+  apiEndpoint: '/api',
+  onSave: (path, content) => {
+    console.log(`Note saved: ${path}`);
+    // Send analytics, show toast notification, etc.
+  },
+  onLoad: (path, content) => {
+    console.log(`Note loaded: ${path}`);
+    document.title = path;
+  },
+  onError: (message, error) => {
+    console.error(message, error);
+    // Show error notification
+  }
+});
+```
+
+## Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+# GitHub
+GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+GITHUB_OWNER=your-username
+GITHUB_REPO=your-notes-repo
+
+# Cloudflare R2
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=your-access-key
+R2_SECRET_ACCESS_KEY=your-secret-key
+R2_BUCKET_NAME=your-bucket
+R2_PUBLIC_URL=https://your-bucket.r2.dev
+```
+
+## Examples
+
+See the `/examples` directory for complete working examples:
+
+- **Express App** - Full Express.js integration
+- **Next.js App** - Integration with Next.js
+- **Static Site** - Vanilla HTML/JS usage
+
+## Styling
+
+The package includes default styles, but you can customize them:
+
+```css
+/* Override default styles */
+.notes-container {
+  font-family: 'Your Custom Font';
+}
+
+.notes-sidebar {
+  background: #your-color;
+}
+
+/* Or create your own theme */
+.notes-container.my-theme {
+  /* Your custom styles */
+}
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Support
+
+For issues and questions, please open an issue on GitHub.