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

npm install markdown-notes-engine

Module Support

This package supports both ES Modules (ESM) and CommonJS (CJS):

ES Modules (import)

import { createNotesRouter, GitHubClient, StorageClient } from 'markdown-notes-engine';

CommonJS (require)

const { createNotesRouter, GitHubClient, StorageClient } = require('markdown-notes-engine');

Backend (Express)

import express from 'express';
import { createNotesRouter } from 'markdown-notes-engine';

const app = express();

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);

const express = require('express');
const { createNotesRouter } = require('markdown-notes-engine');

const app = express();

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)

<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 - Complete API reference and usage guide
• Express Example - 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

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
│   │   ├── *.js          # CommonJS modules
│   │   └── *.mjs         # ES modules
│   ├── frontend/          # Editor UI component
│   ├── index.js           # Main entry (CommonJS)
│   └── index.mjs          # Main entry (ES modules)
├── examples/              # Usage examples
│   └── express-app/       # Express integration example
├── server.js              # Demo server
├── public/                # Demo frontend
└── package.json           # Package configuration (dual module support)

Running the Demo

# 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 for details

Support

• 📖 Documentation
• 💬 Issues
• 📧 Contact

Acknowledgments

Built with:

• Express - Web framework
• Marked - Markdown parser
• Highlight.js - Syntax highlighting
• Octokit - GitHub API client
• AWS SDK - S3/R2 client

Made with ❤️ for markdown lovers everywhere