personotes/README.md

PersoNotes

A lightweight, web-based Markdown note-taking application with a Go backend and a minimalist frontend built with htmx.

• 🚫 No database
• 📝 Flat files: Markdown with front matter
• 🔒 Your notes, your application, your server, your data
• ⌨️ Vim Mode
• 🎹 Keyboard driven with shortcuts and "/" commands
• 🔍 Powerful Search
• 🌍 Run everywhere (Linux & FreeBSD)
• 📱 Responsive on laptop and smartphone
• 🛠️ Super Easy to build
• 🚀 Powerful REST API

Features

• File-based Notes: All notes are stored as plain Markdown files (.md) on the filesystem.
• Daily Notes: Quick daily journaling with interactive calendar, keyboard shortcuts (Ctrl/Cmd+D), and structured templates.
• Tag Indexing: Notes are indexed by tags specified in their YAML front matter, enabling quick search.
• CodeMirror 6 Editor: Modern, powerful Markdown editor with syntax highlighting, One Dark theme, and optional Vim mode.
• Vim Mode: Full Vim keybindings support (hjkl navigation, modes, commands) for power users.
• Live Markdown Preview: Side-by-side editor and live preview pane with scroll synchronization.
• Automatic Front Matter: Automatically generates and updates title, date (creation), last_modified, and tags in YAML front matter.
• Slash Commands: Insert common Markdown elements and dynamic content (like current date) using / commands in the editor.
• Search Modal: Press Ctrl/Cmd+K to open a powerful search modal with keyboard navigation and real-time results.
• Favorites System: Star your most important notes and folders for quick access from the sidebar.
• Keyboard Shortcuts: 10+ global shortcuts for navigation, editing, and productivity (documented in About page).
• 8 Dark Themes: Choose from Material Dark, Monokai, Dracula, One Dark, Solarized, Nord, Catppuccin, and Everforest.
• Font Customization: Select from 8 fonts (JetBrains Mono, Fira Code, Inter, etc.) with 4 size options.
• Interactive Calendar: Monthly calendar widget showing daily notes with visual indicators and one-click access.
• Dynamic File Tree: Automatically updating file tree in the sidebar to navigate notes.
• Hierarchical Organization: Organize notes in folders with drag-and-drop file management.
• Rich Search: Search by keywords, tags (tag:projet), title (title:meeting), or path (path:backend).
• REST API: Full REST API (/api/v1/notes) for programmatic access - list, read, create, update, and delete notes via HTTP.
• Lightweight Frontend: Built with htmx for dynamic interactions, minimizing JavaScript complexity.
• Go Backend: Fast and efficient Go server handles file operations, indexing, and serving the frontend.

Roadmap

• Share notes as Markdown/PDF exports
• Public notes
• User authentication (use Authelia/Authentik for now)

Getting Started

Prerequisites

• Go (version 1.22 or higher recommended)

Installation

1. Clone the repository:

   git clone https://github.com/mathieu/personotes.git
   cd personotes
   

2. Download Go modules:

   go mod tidy
   

Frontend Build Process

The frontend uses Vite to bundle CodeMirror 6 and other JavaScript modules. This step is required for the editor to work.

1. Install Node.js dependencies (first time only):

   cd frontend
   npm install
   

2. Build the frontend:

   npm run build
   

   This compiles frontend/src/ files into static/dist/ (served by Go).

3. Development mode (auto-rebuild on changes):

   npm run build -- --watch
   

Running the Application

1. Build the frontend (see above, required!)

2. Start the Go backend server:

   go run ./cmd/server
   

3. Access the application at http://localhost:8080

Production build:

# Build frontend
cd frontend && npm run build && cd ..

# Compile Go binary
go build -o server ./cmd/server

# Run
./server

Server Configuration

# Custom port
go run ./cmd/server -addr :3000

# Custom notes directory
go run ./cmd/server -notes-dir ~/my-notes

# Both
go run ./cmd/server -addr :3000 -notes-dir ~/my-notes

Technologies Used

• Backend: Go
  • net/http: Standard library for the web server.
  • github.com/fsnotify/fsnotify: For watching file system changes and re-indexing.
  • gopkg.in/yaml.v3: For parsing and marshaling YAML front matter.
• Frontend: HTML, CSS, JavaScript
  • htmx: For dynamic UI interactions without writing much JavaScript.
  • CodeMirror 6: For the robust Markdown editor.
  • Vite: For bundling frontend JavaScript modules.
  • marked.js: For client-side Markdown parsing in the preview.
  • DOMPurify: For sanitizing HTML output from Markdown to prevent XSS vulnerabilities.
  • Highlight.js: For syntax highlighting in code blocks.
  • Custom CSS theme with dark mode inspired by VS Code and GitHub Dark.

Documentation

Getting Started:

• docs/USAGE_GUIDE.md - Complete usage guide from basics to advanced features
• docs/FREEBSD_BUILD.md - FreeBSD build and deployment guide

Features:

• docs/DAILY_NOTES.md - Daily notes guide and template customization
• docs/KEYBOARD_SHORTCUTS.md - Complete keyboard shortcuts reference
• API.md - REST API documentation with examples

Technical:

• docs/ARCHITECTURE_OVERVIEW.md - Architecture, technology stack, and design principles
• ARCHITECTURE.md - Complete system architecture, patterns, and best practices
• CLAUDE.md - Development guide and implementation details
• CHANGELOG.md - Version history and release notes

Quick Start Guide

1. Create your first note: Press Ctrl/Cmd+D to open today's daily note
2. Start writing: Use the Markdown editor with live preview
3. Save: Press Ctrl/Cmd+S or click "Save"
4. Search: Press Ctrl/Cmd+K to find any note instantly
5. Customize: Click ⚙️ to choose themes, fonts, and enable Vim mode

→ Complete usage guide: docs/USAGE_GUIDE.md

Key Features at a Glance

• Daily Notes: Ctrl/Cmd+D for instant journaling with structured templates
• Quick Search: Ctrl/Cmd+K opens search modal with keyboard navigation
• Slash Commands: Type / in editor for quick Markdown formatting
• Favorites: Star notes/folders for quick access (★ icon in sidebar)
• 8 Dark Themes: Material Dark, Monokai, Dracula, One Dark, Nord, and more
• Vim Mode: Full Vim keybindings support (optional)
• 10+ Keyboard Shortcuts: Complete keyboard-driven workflow

REST API

Full REST API for programmatic access:

# List all notes
curl http://localhost:8080/api/v1/notes

# Get a note (JSON or Markdown)
curl http://localhost:8080/api/v1/notes/path/to/note.md

# Create/update a note
curl -X PUT http://localhost:8080/api/v1/notes/new-note.md \
  -H "Content-Type: application/json" \
  -d '{"body": "# Content", "frontMatter": {"title": "Title"}}'

# Delete a note
curl -X DELETE http://localhost:8080/api/v1/notes/old-note.md

→ Complete API documentation: API.md