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

Clone the repository:

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

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.

Install Node.js dependencies (first time only):
```
cd frontend
npm install
```
Build the frontend:
```
npm run build
```
This compiles frontend/src/ files into static/dist/ (served by Go).
Development mode (auto-rebuild on changes):
```
npm run build -- --watch
```

Running the Application

Build the frontend (see above, required!)
Start the Go backend server:
```
go run ./cmd/server
```
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

Create your first note: Press Ctrl/Cmd+D to open today's daily note
Start writing: Use the Markdown editor with live preview
Save: Press Ctrl/Cmd+S or click "Save"
Search: Press Ctrl/Cmd+K to find any note instantly
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

Languages

JavaScript 36.5%

Go 25.2%

CSS 20.3%

HTML 13.6%

Shell 4.4%