personotes/README.md

Project Notes

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

• 🚫 No database
• 📝 Pure Markdown with flat files
• 🔒 Your notes, your server
• ⌨️ Vim Mode
• 🎹 Keyboard driven
• 🌍 Run everywhere (Linux & FreeBSD)
• 🛠️ Easy to build
• 🚀 Powerful 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.

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.

Architecture

Project Notes uses a hybrid architecture that combines:

• Go Backend: Fast, type-safe server handling file operations and indexing
• HTMX: "HTML over the wire" for dynamic interactions with minimal JavaScript
• Modern JavaScript: CodeMirror 6, drag-and-drop, and UI enhancements
• Vite: Modern build tool for efficient JavaScript bundling

Key Design Principles:

• Server renders HTML, not JSON (simpler, faster)
• HTMX handles all AJAX and DOM updates (consistent, reliable)
• JavaScript enhances UI (editor, drag-and-drop, animations)
• Event-driven coordination between HTMX and JavaScript

For detailed documentation, see:

• docs/DAILY_NOTES.md - Complete daily notes guide and customization
• ARCHITECTURE.md - Complete system architecture, patterns, and best practices
• CLAUDE.md - Development guide and implementation details
• API.md - REST API documentation
• CHANGELOG.md - Version history and release notes

Getting Started

Prerequisites

• Go (version 1.22 or higher recommended)

Installation

1. Clone the repository:

   git clone https://github.com/mathieu/project-notes.git
   cd project-notes
   

2. Download Go modules:

   go mod tidy
   

Frontend Build Process

IMPORTANT: The frontend must be built before running the application.

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

Usage

Daily Notes (Quick Start)

The fastest way to start taking notes:

1. Press Ctrl/Cmd+D or click "📅 Note du jour" in the header
2. A note for today is automatically created with a structured template
3. Start writing in sections: Objectifs, Notes, Accompli, Réflexions, Liens

Using the Calendar:

• Navigate months with ‹ and › arrows
• Click any date to open/create that day's note
• Blue dots (●) indicate existing notes
• Check "Récentes" for quick access to the last 7 days

For complete daily notes documentation, see docs/DAILY_NOTES.md

Creating a New Note

1. Click the "✨ Nouvelle note" button in the header.
2. Enter a filename (e.g., my-new-note.md) in the modal dialog.
3. Click "Créer / Ouvrir" - if the note exists, it will be opened; otherwise, a new note will be created.
4. An editor will appear with pre-filled YAML front matter (title, creation date, last modified date, and a "default" tag).

Editing a Note

1. Click on a note in the "Notes" file tree in the sidebar.
2. The note's content will load into the editor.
3. Make your changes in the left pane (textarea). The right pane will show a live preview.
4. Click the "Enregistrer" button or use Ctrl/Cmd+S to save your changes. The last_modified date in the front matter will be updated automatically.

Searching Notes

Quick Search Modal (Recommended):

1. Press Ctrl/Cmd+K anywhere to open the search modal.
2. Type your query - results appear instantly with keyboard navigation.
3. Use ↑/↓ to navigate, Enter to open, Esc to close.

Search Syntax (works in both modal and header search):

1. General search: Type keywords to search across title, tags, path, and content.
2. Tag filter: Use tag:projet to filter by specific tags.
3. Title filter: Use title:meeting to search within note titles.
4. Path filter: Use path:backend to search by file path.
5. Quoted phrases: Use "exact phrase" to search for exact matches.

Results are scored and ranked by relevance (title matches score highest).

Using Slash Commands

1. While editing a note, type / at the start of a line in the textarea.
2. A command palette will appear with available commands.
3. Type to filter commands (e.g., /h1, /date, /table).
4. Use ArrowUp/ArrowDown to navigate and Enter or Tab to select a command.
5. The corresponding Markdown snippet will be inserted at your cursor position.

Available commands: h1, h2, h3, list, date, link, bold, italic, code, codeblock, quote, hr, table

Customization & Settings

Access settings by clicking the ⚙️ Paramètres button in the sidebar.

Theme Selection (8 options):

• Material Dark (default) - Professional Material Design theme
• Monokai Dark - Classic Monokai palette
• Dracula - Elegant purple and cyan accents
• One Dark - Popular Atom theme
• Solarized Dark - Scientifically optimized colors
• Nord - Arctic blue-toned theme
• Catppuccin - Pastel comfort palette
• Everforest - Nature-inspired green and beige

Font Customization:

• Fonts: JetBrains Mono (default), Fira Code, Inter, Poppins, Public Sans, Cascadia Code, Source Code Pro, Sans-serif
• Sizes: Small (14px), Medium (16px), Large (18px), X-Large (20px)

Editor Settings:

• Vim Mode: Enable full Vim keybindings in CodeMirror
  • hjkl navigation, insert/normal/visual modes
  • All standard Vim commands and motions
  • Requires @replit/codemirror-vim package

Keyboard Shortcuts

Press Ctrl/Cmd+K or visit the About page (ℹ️ button in sidebar) for the complete list:

• Ctrl/Cmd+K - Open search
• Ctrl/Cmd+S - Save note
• Ctrl/Cmd+D - Open daily note
• Ctrl/Cmd+N - Create new note
• Ctrl/Cmd+H - Go home
• Ctrl/Cmd+B - Toggle sidebar
• Ctrl/Cmd+, - Open settings
• Ctrl/Cmd+P - Toggle preview
• Ctrl/Cmd+Shift+F - Create new folder
• Escape - Close modals

Favorites System

Star important notes and folders for quick access:

1. Hover over any note or folder in the sidebar
2. Click the ★ icon to add/remove from favorites
3. Access favorites from the ⭐ Favoris section in the sidebar
4. Favorites persist across sessions (stored in .favorites.json)

Organizing Notes in Folders

1. Click the "📁 Nouveau dossier" button in the sidebar.
2. Enter a folder path (e.g., projets or projets/backend).
3. The folder will be created and appear in the file tree.
4. Drag and drop notes between folders to reorganize them.

Deleting a Note

1. Load the note you wish to delete into the editor.
2. Click the "Supprimer" button.
3. Confirm the deletion when prompted. The note will be removed from the filesystem and the file tree will update automatically.

Server Configuration

The server accepts the following command-line flags:

• -addr :PORT - Change server address (default: :8080)
• -notes-dir PATH - Change notes directory (default: ./notes)

Example:

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

REST API

Project Notes includes a full REST API for programmatic access to your notes.

Base URL: http://localhost:8080/api/v1

Quick Examples

List all notes:

curl http://localhost:8080/api/v1/notes

Get a specific note (JSON):

curl http://localhost:8080/api/v1/notes/projet/backend.md

Get note as Markdown:

curl http://localhost:8080/api/v1/notes/projet/backend.md \
  -H "Accept: text/markdown"

Create/Update a note:

curl -X PUT http://localhost:8080/api/v1/notes/test.md \
  -H "Content-Type: application/json" \
  -d '{
    "body": "\n# Test\n\nContent here...",
    "frontMatter": {
      "title": "Test Note",
      "tags": ["test"]
    }
  }'

Delete a note:

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

Full API Documentation

See API.md for complete documentation including:

• All endpoints (LIST, GET, PUT, DELETE)
• Request/response formats
• Content negotiation (JSON/Markdown)
• Advanced examples (sync, backup, automation)
• Integration guides

Use Cases

• Backup: Automate note backups with cron jobs
• Sync: Synchronize notes across machines
• Integration: Connect with other tools (Obsidian, Notion, etc.)
• Automation: Create notes programmatically (daily notes, templates)
• CI/CD: Validate Markdown in pipelines

⚠️ Security Note: The API currently has no authentication. Use a reverse proxy (nginx, Caddy) with auth if exposing publicly.