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
- 📝 Fat files : Markdown with frontmatters
- 🔒 Your notes, your application, your server, your data
- ⌨️ Vim Mode
- 🎹 Keyboard driven
- 🔍 Powerful Search
- 🌍 Run everywhere (Linux & FreeBSD)
- 📱 Responsive with laptop and smartphone
- 🛠️ Super Easy to build
- 🚀 A 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](https://htmx.org/): For dynamic UI interactions without writing much JavaScript.
    *   [CodeMirror 6](https://codemirror.net/6/): For the robust Markdown editor.
    *   [Vite](https://vitejs.dev/): For bundling frontend JavaScript modules.
    *   [marked.js](https://marked.js.org/): For client-side Markdown parsing in the preview.
    *   [DOMPurify](https://dompurpurify.com/): For sanitizing HTML output from Markdown to prevent XSS vulnerabilities.
    *   [Highlight.js](https://highlightjs.org/): 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](./docs/USAGE_GUIDE.md)** - Complete usage guide from basics to advanced features
- **[docs/FREEBSD_BUILD.md](./docs/FREEBSD_BUILD.md)** - FreeBSD build and deployment guide

**Features**:
- **[docs/DAILY_NOTES.md](./docs/DAILY_NOTES.md)** - Daily notes guide and template customization
- **[docs/KEYBOARD_SHORTCUTS.md](./docs/KEYBOARD_SHORTCUTS.md)** - Complete keyboard shortcuts reference
- **[API.md](./API.md)** - REST API documentation with examples

**Technical**:
- **[docs/ARCHITECTURE_OVERVIEW.md](./docs/ARCHITECTURE_OVERVIEW.md)** - Architecture, technology stack, and design principles
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Complete system architecture, patterns, and best practices
- **[CLAUDE.md](./CLAUDE.md)** - Development guide and implementation details
- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and release notes

## Getting Started

### Prerequisites

*   [Go](https://go.dev/doc/install) (version 1.22 or higher recommended)

### Installation

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/mathieu/project-notes.git
    cd project-notes
    ```
2.  **Download Go modules:**
    ```bash
    go mod tidy
    ```

### Frontend Build Process

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

The frontend uses [Vite](https://vitejs.dev/) 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):
    ```bash
    cd frontend
    npm install
    ```

2.  **Build the frontend**:
    ```bash
    npm run build
    ```

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

3.  **Development mode** (auto-rebuild on changes):
    ```bash
    npm run build -- --watch
    ```

### Running the Application

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

2.  **Start the Go backend server**:
    ```bash
    go run ./cmd/server
    ```

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

**Production build**:
```bash
# Build frontend
cd frontend && npm run build && cd ..

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

# Run
./server
```

## 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 "Enregistrer"
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](./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:

```bash
# 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](./API.md)

## Server Configuration

```bash
# 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
```