mathieu/personotes
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Des tonnes de modifications notamment VIM / Couleurs / typos

Browse Source
This commit is contained in:
Mathieu Aumont
2025-11-11 15:41:51 +01:00
parent 439880b08f
commit 6face7a02f
59 changed files with 7857 additions and 960 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
GEMINI.md
View File

@ -1,19 +1,30 @@
# Project Notes
# GEMINI.md
A lightweight, web-based Markdown note-taking application with a Go backend and a minimalist frontend built with htmx. It allows users to create, edit, delete, and search Markdown notes, with automatic front matter management and a live Markdown preview.
This file provides guidance to Google's Gemini models when working with code in this repository.
## Project Overview
A lightweight, web-based Markdown note-taking application with a Go backend and a modern JavaScript frontend. Notes are stored as plain Markdown files with YAML front matter containing metadata (title, date, last_modified, tags). The system provides a sophisticated CodeMirror 6 editor with live preview, rich search capabilities, hierarchical organization, and automatic front matter management.
The project uses a hybrid architecture combining a Go backend, htmx for dynamic interactions, and a modern JavaScript frontend built with Vite and CodeMirror 6.
## 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.
* **Live Markdown Preview:** A side-by-side editor and live preview pane for a better writing experience.
* **CodeMirror 6 Editor:** Modern, powerful Markdown editor with syntax highlighting and One Dark theme.
* **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.
* **Dynamic File Tree:** An automatically updating file tree in the sidebar to navigate notes.
* **Lightweight Frontend:** Built with htmx for dynamic interactions, minimizing JavaScript complexity.
* **Search Modal:** Press `Ctrl/Cmd+K` to open a powerful search modal with keyboard navigation and real-time results.
* **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`).
* **Go Backend:** A fast and efficient Go server handles file operations, indexing, and serving the frontend.
* **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
@ -23,102 +34,168 @@ A lightweight, web-based Markdown note-taking application with a Go backend and
* `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.
### Frontend Build Process
## Architecture
The frontend assets (JavaScript, CSS) are built and optimized using [Vite](https://vitejs.dev/). When changes are made to the frontend source code (e.g., in `frontend/src/`), the `npm run build` command must be executed from the `frontend/` directory. This command compiles, bundles, and minifies the source files into static assets (located in `static/dist/`) that the Go backend serves to the browser. This step is crucial to ensure that the latest frontend changes are reflected in the application.
The project 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**: For UI enhancements like the CodeMirror 6 editor, drag-and-drop, and animations.
- **Vite**: Modern build tool for efficient JavaScript bundling.
## Getting Started
### Backend (Go)
Located under `internal/`, the backend has three main packages:
- **`indexer`**: Maintains an in-memory index of notes, parsing YAML front matter. It's thread-safe using `sync.RWMutex`.
- **`watcher`**: Uses `fsnotify` to monitor the notes directory for changes and triggers re-indexing (with a 200ms debounce).
- **`api`**: Contains HTTP handlers for serving HTML templates and handling CRUD operations on notes. It automatically manages front matter on save.
The server entrypoint is `cmd/server/main.go`.
### Frontend
The frontend source is in `frontend/src/` and is built using Vite.
- **`main.js`**: The entry point that imports all other modules.
- **`editor.js`**: Implements the CodeMirror 6 editor, live preview, scroll sync, and slash commands.
- **`file-tree.js`**: Handles the interactive file tree, including drag-and-drop functionality.
- **`search.js`**: Implements the `Ctrl/Cmd+K` search modal.
- **`ui.js`**: Handles general UI interactions like toggling the sidebar.
### HTMX + JavaScript Coordination
The core principle is that **HTMX handles all server interactions and DOM updates**, while **JavaScript provides client-side UI enhancements**.
- **Flow**: User Interaction → HTMX (AJAX) → Go Server (sends HTML) → HTMX (swaps DOM) → JS listens to `htmx:*` events to enhance the new content.
- **Best Practice**: Use `htmx.ajax()` for JS-initiated requests and listen to HTMX events (`htmx:afterSwap`, `htmx:oobAfterSwap`) instead of using `MutationObserver`. This creates a more performant and maintainable system. The server uses out-of-band (OOB) swaps to update multiple parts of the UI at once (e.g., updating the file tree after saving a note).
## Development Workflow
### Prerequisites
* [Go](https://go.dev/doc/install) (version 1.22 or higher recommended)
* [Go](https://go.dev/doc/install) (version 1.22 or higher)
* [Node.js](https://nodejs.org/) (for the frontend build process)
### Installation
### Frontend Build Process
1. **Clone the repository:**
**IMPORTANT**: The frontend JavaScript must be built before running the application. The compiled assets are required for the editor and other interactive features to work.
1. **Install Node.js dependencies** (first time only):
```bash
git clone https://github.com/mathieu/project-notes.git
cd project-notes
cd frontend
npm install
```
2. **Download Go modules:**
2. **Build the frontend for production**:
```bash
go mod tidy
npm run build
```
This command compiles, bundles, and minifies the source files from `frontend/src/` into the `static/dist/` directory.
3. **Run in watch mode for development**:
```bash
npm run build -- --watch
```
This will automatically rebuild the frontend assets when you make changes to the source files.
### Running the Application
To start the Go backend server:
1. Ensure the **frontend has been built** at least once.
2. Start the Go backend server from the project root:
```bash
go run ./cmd/server
```
3. The application will be accessible at `http://localhost:8080`.
```bash
go run ./cmd/server
```
The application will be accessible in your web browser at `http://localhost:8080`.
## Usage
### 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
The search supports multiple query formats:
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
### 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
### 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:
Example: `go run ./cmd/server -addr :3000 -notes-dir ~/my-notes`
### Testing
Run all Go tests:
```bash
go run ./cmd/server -addr :3000 -notes-dir ~/my-notes
```
go test ./...
```
## Key Implementation Details
### CodeMirror 6 Editor
Implemented in `frontend/src/editor.js`, the editor features:
- **Markdown Support**: Full syntax highlighting via `@codemirror/lang-markdown`.
- **Theme**: `one-dark` theme for a VS Code-like feel.
- **Live Preview**: A preview pane that updates 150ms after you stop typing.
- **Scroll Sync**: The editor and preview scroll in unison.
- **Auto-Save**: Automatically saves the note 2 seconds after inactivity.
- **Slash Commands**: A command palette triggered by `/` for inserting Markdown snippets.
### Slash Commands
A productivity feature in the editor (`frontend/src/editor.js`).
- **Trigger**: Type `/` at the start of a line.
- **Commands**: Includes `h1`, `h2`, `h3`, `list`, `date`, `link`, `bold`, `italic`, `code`, `codeblock`, `quote`, `hr`, `table`.
- **Interaction**: Navigate with arrow keys, select with `Enter` or `Tab`.
### Search
- **Modal**: A fast search modal is available via `Ctrl/Cmd+K`.
- **Syntax**: Supports general keywords, `tag:value`, `title:value`, `path:value`, and `"quoted phrases"`.
- **Ranking**: Results are scored by relevance, with title matches scoring highest.
### REST API
A full REST API is available under `/api/v1/` for programmatic access. See `API.md` for detailed documentation.
- **Endpoints**: `GET /notes`, `GET /notes/{path}`, `PUT /notes/{path}`, `DELETE /notes/{path}`.
- **Content Negotiation**: Supports `application/json` and `text/markdown`.
### Security
- **Path Traversal**: The backend validates all file paths to prevent access outside the notes directory.
- **XSS**: `DOMPurify` is used to sanitize HTML rendered from Markdown, preventing Cross-Site Scripting attacks.
- **API Security**: The REST API has no authentication by default. It is recommended to place it behind a reverse proxy with authentication if exposing it publicly.
### Recent Fixes
- **Bulk Deletion 404 Error**: The issue with bulk deletion returning a 404 error has been resolved. The `DELETE /api/files/delete-multiple` endpoint now correctly processes requests. This involved:
- Changing the HTTP method from `POST` to `DELETE` in both `frontend/src/file-tree.js` and `internal/api/handler.go`.
- Adapting the Go backend handler (`handleDeleteMultiple`) to manually read and parse the URL-encoded request body for `DELETE` requests, as `r.ParseForm()` does not automatically process bodies for this method.
## Project Structure
```
project-notes/
├── cmd/server/main.go # Server entry point
├── internal/ # Go backend packages (api, indexer, watcher)
│ ├── api/
│ ├── indexer/
│ └── watcher/
├── frontend/ # Frontend source and build configuration
│ ├── src/
│ │ ├── main.js # JS entry point
│ │ ├── editor.js # CodeMirror 6 editor
│ │ ├── file-tree.js # Drag-and-drop file tree
│ │ ├── search.js # Search modal
│ │ └── ui.js # Misc UI scripts
│ ├── package.json
│ └── vite.config.js
├── static/ # Served static assets
│ ├── dist/ # Compiled/bundled frontend assets (generated by Vite)
│ └── theme.css # Main stylesheet
├── templates/ # Go HTML templates
├── notes/ # Default directory for user's Markdown notes
├── go.mod
├── API.md # REST API documentation
├── ARCHITECTURE.md # Detailed architecture document
└── GEMINI.md # This file
```