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

Add backlink

Browse Source
This commit is contained in:
Mathieu Aumont
2025-11-12 09:31:09 +01:00
parent 5e30a5cf5d
commit 584a4a0acd
25 changed files with 1769 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

272
CLAUDE.md
View File

@ -6,16 +6,29 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
A lightweight web-based Markdown note-taking application with a Go backend and 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.
**Key Features**:
- **Daily Notes**: Quick daily journaling with interactive calendar, keyboard shortcuts (Ctrl/Cmd+D), and structured templates
- **Favorites System**: Star important notes and folders for quick access from the sidebar
- **Note Linking**: Create links between notes with `/link` command and fuzzy search modal
- **Vim Mode**: Full Vim keybindings support (hjkl navigation, modes, commands) for power users
- **Multiple Themes**: 8 dark themes (Material Dark, Monokai, Dracula, One Dark, Solarized, Nord, Catppuccin, Everforest)
- **Font Customization**: 8 fonts (JetBrains Mono, Fira Code, Inter, etc.) with 4 size options
- **Keyboard Shortcuts**: 10+ global shortcuts for navigation, editing, and productivity
**Recent Modernization**: The project has been migrated from a simple textarea editor to CodeMirror 6, with a Vite build system for frontend modules. The backend remains unchanged, maintaining the same Go architecture with htmx for dynamic interactions.
## Architecture
### Backend (Go)
Three main packages under `internal/`:
Four main packages under `internal/`:
- **indexer**: Maintains an in-memory index mapping tags to note files. Parses YAML front matter from `.md` files to build the index. Thread-safe with RWMutex.
- **watcher**: Uses `fsnotify` to monitor filesystem changes and trigger re-indexing with 200ms debounce. Recursively watches all subdirectories.
- **api**: HTTP handlers that serve templates and handle CRUD operations on notes. Updates front matter automatically on save.
- `handler.go` - Main HTML endpoints for the web interface
- `rest_handler.go` - REST API endpoints (v1)
- `daily_notes.go` - Daily note creation and calendar functionality
- `favorites.go` - Favorites management (star/unstar notes and folders)
The server (`cmd/server/main.go`) coordinates these components:
1. Loads initial index from notes directory
@ -30,6 +43,8 @@ The server (`cmd/server/main.go`) coordinates these components:
- `/api/folders/create` (Folder management)
- `/api/files/move` (File/folder moving)
- `/api/home` (Home page)
- `/api/daily-notes/*` (Daily note creation and calendar)
- `/api/favorites/*` (Favorites management)
5. Handles static files from `static/` directory
### Frontend
@ -46,22 +61,33 @@ The frontend uses a modern build system with Vite and CodeMirror 6:
#### Frontend Source Structure
```
frontend/src/
├── main.js # Entry point - imports all modules
├── editor.js # CodeMirror 6 editor implementation with slash commands
├── search.js # Search modal with Ctrl/Cmd+K keyboard shortcut
├── file-tree.js # Drag-and-drop file organization
└── ui.js # Sidebar toggle functionality
├── main.js # Entry point - imports all modules
├── editor.js # CodeMirror 6 editor implementation with slash commands
├── vim-mode-manager.js # Vim mode integration for CodeMirror
├── search.js # Search modal with Ctrl/Cmd+K keyboard shortcut
├── link-inserter.js # Note linking modal for /link command
├── file-tree.js # Drag-and-drop file organization
├── favorites.js # Favorites system (star/unstar functionality)
├── daily-notes.js # Daily notes creation and calendar widget
├── keyboard-shortcuts.js # Global keyboard shortcuts management
├── theme-manager.js # Theme switching and persistence
├── font-manager.js # Font selection and size management
└── ui.js # Sidebar toggle functionality
```
#### CodeMirror 6 Editor Features
- **Syntax Highlighting**: Full Markdown language support (`@codemirror/lang-markdown`)
- **Theme**: One Dark theme (`@codemirror/theme-one-dark`) - VS Code-inspired dark theme
- **Vim Mode**: Optional full Vim keybindings (`@replit/codemirror-vim`) with hjkl navigation, modes, and commands
- **Live Preview**: Debounced updates (150ms) synchronized with editor scroll position
- **Auto-Save**: Triggers after 2 seconds of inactivity
- **Keyboard Shortcuts**:
- `Ctrl/Cmd+S` for manual save
- `Ctrl/Cmd+D` for daily notes
- `Ctrl/Cmd+K` for search
- `Ctrl/Cmd+B` for sidebar toggle
- `Tab` for proper indentation
- Full keyboard navigation
- Full keyboard navigation (see docs/KEYBOARD_SHORTCUTS.md)
- **View Modes**: Toggle between split view, editor-only, and preview-only
- **Slash Commands**: Type `/` to open command palette for quick Markdown insertion
- **Front Matter Handling**: Automatically strips YAML front matter in preview
@ -71,12 +97,21 @@ frontend/src/
- **Drag & Drop**: Move files between folders with visual feedback
- **Folder Creation**: Modal-based creation supporting nested paths
- **Safe Validation**: Prevents dangerous path operations
- **Favorites**: Star notes and folders for quick access (★ icon in sidebar)
#### Rendering Pipeline
- **marked.js**: Markdown to HTML conversion
- **DOMPurify**: HTML sanitization to prevent XSS attacks
- **Highlight.js**: Syntax highlighting for code blocks in preview
- **Custom Theme**: Material Darker theme in `static/theme.css` with CSS custom properties
- **Custom Themes**: 8 dark themes in `static/theme.css` with CSS custom properties
- Material Dark (default)
- Monokai
- Dracula
- One Dark
- Solarized Dark
- Nord
- Catppuccin
- Everforest
### HTMX + JavaScript Coordination (Optimized Architecture)
@ -227,6 +262,33 @@ htmx.ajax('POST', '/api/files/move', {
- Use MutationObserver when HTMX events are available
- Mix fetch() and htmx.ajax() for similar operations
### Daily Notes
**Implementation**: `internal/api/daily_notes.go` and `frontend/src/daily-notes.js`
Daily notes provide a quick journaling feature:
- **Keyboard Shortcut**: `Ctrl/Cmd+D` creates or opens today's note
- **Calendar Widget**: Interactive monthly calendar showing all daily notes
- **Template System**: Uses `daily-note-template.md` if present in notes directory
- **Auto-naming**: Creates notes as `daily/YYYY-MM-DD.md` by default
- **Visual Indicators**: Calendar highlights days with existing notes
- **One-click Access**: Click any calendar date to open or create that day's note
The calendar is implemented using htmx for dynamic month navigation and rendering.
### Favorites System
**Implementation**: `internal/api/favorites.go` and `frontend/src/favorites.js`
The favorites system allows quick access to frequently used notes and folders:
- **Star Icon**: Click ★ next to any note or folder in the file tree
- **Persistence**: Favorites stored in `.favorites.json` in the notes directory
- **Quick Access**: Starred items appear at the top of the sidebar
- **Folder Support**: Star entire folders to quickly access project areas
- **Visual Feedback**: Filled star (★) for favorites, empty star (☆) for non-favorites
Favorites are loaded on server startup and updated in real-time via htmx.
### Note Format
Notes have YAML front matter with these fields:
@ -258,12 +320,13 @@ Output files (loaded by templates):
- `static/dist/project-notes-frontend.umd.js` (UMD format)
Frontend dependencies (from `frontend/package.json`):
- `@codemirror/basic-setup` - Base editor functionality
- `@codemirror/lang-markdown` - Markdown language support
- `@codemirror/state` - Editor state management
- `@codemirror/view` - Editor view layer
- `@codemirror/theme-one-dark` - Dark theme
- `vite` - Build tool
- `@codemirror/basic-setup` (^0.20.0) - Base editor functionality
- `@codemirror/lang-markdown` (^6.5.0) - Markdown language support
- `@codemirror/state` (^6.5.2) - Editor state management
- `@codemirror/view` (^6.38.6) - Editor view layer
- `@codemirror/theme-one-dark` (^6.1.3) - Dark theme
- `@replit/codemirror-vim` (^6.2.2) - Vim mode integration
- `vite` (^7.2.2) - Build tool
### Running the Server
@ -415,6 +478,78 @@ A modern command-palette style search modal is available:
**Styling**: Custom styles in `static/theme.css` with Material Darker theme integration.
### Theme and Font Customization
**Implementation**: `frontend/src/theme-manager.js` and `frontend/src/font-manager.js`
The application supports extensive UI customization:
#### Themes
8 dark themes available via Settings (⚙️ icon):
- **Material Dark** (default) - Material Design inspired
- **Monokai** - Classic Monokai colors
- **Dracula** - Popular purple-tinted theme
- **One Dark** - Atom/VS Code inspired
- **Solarized Dark** - Precision colors by Ethan Schoonover
- **Nord** - Arctic, north-bluish color palette
- **Catppuccin** - Soothing pastel theme
- **Everforest** - Comfortable greenish theme
Themes are applied via CSS custom properties and persist in localStorage.
#### Fonts
8 font options with 4 size presets (small, medium, large, extra-large):
- JetBrains Mono (default)
- Fira Code
- Inter
- IBM Plex Mono
- Source Code Pro
- Cascadia Code
- Roboto Mono
- Ubuntu Mono
Font settings apply to both the editor and preview pane.
### Vim Mode
**Implementation**: `frontend/src/vim-mode-manager.js` using `@replit/codemirror-vim`
Optional Vim keybindings for power users:
- **Enable/Disable**: Toggle via Settings (⚙️ icon)
- **Full Vim Support**: hjkl navigation, visual mode, operators, text objects
- **Mode Indicator**: Shows current Vim mode (Normal/Insert/Visual) in editor
- **Persistence**: Vim mode preference saved to localStorage
- **CodeMirror Integration**: Native Vim extension with excellent compatibility
Vim mode users get full modal editing while maintaining CodeMirror features like syntax highlighting and auto-save.
### Keyboard Shortcuts
**Implementation**: `frontend/src/keyboard-shortcuts.js`
The application provides 10+ global keyboard shortcuts for efficient navigation:
**Essential Shortcuts**:
- `Ctrl/Cmd+D` - Create or open today's daily note
- `Ctrl/Cmd+K` - Open search modal
- `Ctrl/Cmd+S` - Save current note (also triggers auto-save)
- `Ctrl/Cmd+B` - Toggle sidebar visibility
- `Ctrl/Cmd+/` - Show keyboard shortcuts help modal
**Editor Shortcuts**:
- `Tab` - Indent (when in editor)
- `Shift+Tab` - Outdent (when in editor)
- `Ctrl/Cmd+Enter` - Save note (alternative to Cmd+S)
**Navigation**:
- `↑`/`↓` - Navigate search results or command palette
- `Enter` - Select/confirm action
- `Esc` - Close modals, cancel actions, clear search
All shortcuts are non-blocking and work across the application. The shortcuts help modal (triggered by `Ctrl/Cmd+/`) provides a quick reference guide.
For complete documentation, see `docs/KEYBOARD_SHORTCUTS.md`.
### Security Considerations
File path validation in `handler.go` and `rest_handler.go`:
@ -509,19 +644,64 @@ Provides command palette for quick Markdown insertion:
The editor includes a slash command system integrated with CodeMirror 6:
- Type `/` at the start of a line to trigger the command palette
- Available commands (13 total):
- Available commands (14 total):
- **Headings**: h1, h2, h3 - Insert Markdown headers
- **Formatting**: bold, italic, code - Text formatting
- **Blocks**: codeblock, quote, hr, table - Block-level elements
- **Lists**: list - Unordered list
- **Dynamic**: date - Insert current date in French format (DD/MM/YYYY)
- **Links**: link - Insert link template `[text](url)`
- **Links**:
- `link` - Insert standard Markdown link `[texte](url)`
- `ilink` - Open internal note linking modal (see Note Linking below)
- Navigate with Arrow Up/Down, select with Enter/Tab, cancel with Escape
- Commands are filtered in real-time as you type after the `/`
- The palette is positioned dynamically near the cursor using CodeMirror coordinates
- Implementation in `frontend/src/editor.js` with the `SlashCommands` class
- Styled command palette with gradient selection indicator
### Note Linking
**Implementation**: `frontend/src/link-inserter.js`
The note linking system allows users to create Markdown links between notes without leaving the editor:
**Activation**: Type `/ilink` (internal link) in the editor and select the command from the slash palette
**Features**:
- **Fuzzy Search**: Real-time search across all notes with 200ms debounce
- **Keyboard Navigation**: Navigate with ↑/↓, select with Enter, cancel with Esc
- **Search Integration**: Reuses existing `/api/search` endpoint (no new backend code)
- **Rich Results**: Shows note title, path, tags, and metadata
- **Instant Insertion**: Inserts `[Note Title](path/to/note.md)` format at cursor position
**Architecture**:
- `LinkInserter` class manages the search modal and selection
- Opens via `SlashCommands.openLinkInserter()` when `/ilink` is triggered
- Uses HTMX search API for consistency
- Modal styled to match `SearchModal` design language
**Workflow**:
1. User types `/ilink` → slash palette appears
2. User selects "ilink" → modal opens with search input
3. User types search query → fuzzy search filters notes
4. User selects note (Enter/click) → Markdown link inserted
5. Modal closes → editor regains focus at end of inserted link
**Standard Links**: For external URLs, use `/link` to insert the standard Markdown template `[texte](url)`
**Link Format**: Links are inserted as HTML with HTMX attributes:
```html
<a href="#" hx-get="/api/notes/path/to/note.md" hx-target="#editor-container" hx-swap="innerHTML">Note Title</a>
```
This format:
- **Clickable in preview**: Links open the note directly in the editor when clicked
- **HTMX-powered**: Uses existing HTMX infrastructure (no new backend code)
- **Inline HTML**: Marked.js renders the HTML as-is, DOMPurify sanitizes it, HTMX processes it
- **Editable**: Plain HTML in the source, can be manually edited if needed
**Note**: This format is specific to this application. For compatibility with other Markdown tools, use standard Markdown links with `/link` command.
## Frontend Libraries
The application uses a mix of npm packages (for the editor) and CDN-loaded libraries (for utilities):
@ -533,7 +713,8 @@ Managed in `frontend/package.json`:
- **@codemirror/state (^6.5.2)**: Editor state management
- **@codemirror/view (^6.38.6)**: Editor view layer and rendering
- **@codemirror/theme-one-dark (^6.1.3)**: Dark theme for CodeMirror
- **vite (^5.0.0)**: Build tool for bundling frontend modules
- **@replit/codemirror-vim (^6.2.2)**: Vim mode integration for CodeMirror
- **vite (^7.2.2)**: Build tool for bundling frontend modules
### CDN Libraries
Loaded in `templates/index.html`:
@ -543,14 +724,16 @@ Loaded in `templates/index.html`:
- **Highlight.js (11.9.0)**: Syntax highlighting for code blocks in preview with Atom One Dark theme
### Styling
- **Material Darker Theme**: Custom dark theme in `static/theme.css`
- **8 Dark Themes**: Switchable themes in `static/theme.css`
- Material Dark, Monokai, Dracula, One Dark, Solarized, Nord, Catppuccin, Everforest
- **Color System**: CSS custom properties for consistent theming
- Background colors: `--bg-primary`, `--bg-secondary`, `--bg-tertiary`, `--bg-elevated`
- Text colors: `--text-primary`, `--text-secondary`, `--text-muted`
- Accent colors: `--accent-blue`, `--accent-violet`
- **Font Customization**: 8 font families with 4 size presets
- **No CSS Framework**: All styles hand-crafted with CSS Grid and Flexbox
- **Responsive Design**: Adaptive layout for different screen sizes
- **Custom Scrollbars**: Styled scrollbars matching the dark theme
- **Custom Scrollbars**: Styled scrollbars matching the current theme
### Build Output
The Vite build process produces:
@ -566,17 +749,28 @@ project-notes/
│ └── main.go # Server entry point
├── internal/
│ ├── api/
│ │ └── handler.go # HTTP handlers for CRUD operations
│ │ ├── handler.go # HTTP handlers for CRUD operations
│ │ ├── rest_handler.go # REST API v1 endpoints
│ │ ├── daily_notes.go # Daily notes functionality
│ │ └── favorites.go # Favorites management
│ ├── indexer/
│ │ └── indexer.go # Note indexing and search
│ │ ├── indexer.go # Note indexing and search
│ │ └── indexer_test.go # Indexer tests
│ └── watcher/
│ └── watcher.go # Filesystem watcher with fsnotify
├── frontend/ # Frontend build system (NEW)
├── frontend/ # Frontend build system
│ ├── src/
│ │ ├── main.js # Entry point
│ │ ├── editor.js # CodeMirror 6 implementation (26 KB)
│ │ ├── file-tree.js # Drag-and-drop file management (11 KB)
│ │ └── ui.js # Sidebar toggle (720 B)
│ │ ├── main.js # Entry point - imports all modules
│ │ ├── editor.js # CodeMirror 6 editor with slash commands
│ │ ├── vim-mode-manager.js # Vim mode integration
│ │ ├── search.js # Search modal (Ctrl/Cmd+K)
│ │ ├── file-tree.js # Drag-and-drop file tree
│ │ ├── favorites.js # Favorites system
│ │ ├── daily-notes.js # Daily notes and calendar widget
│ │ ├── keyboard-shortcuts.js # Global keyboard shortcuts
│ │ ├── theme-manager.js # Theme switching
│ │ ├── font-manager.js # Font customization
│ │ └── ui.js # Sidebar toggle
│ ├── package.json # NPM dependencies
│ ├── package-lock.json
│ └── vite.config.js # Vite build configuration
@ -592,9 +786,18 @@ project-notes/
│ ├── search-results.html # Search results
│ └── new-note-prompt.html # New note modal
├── notes/ # Note storage directory
│ └── *.md # Markdown files with YAML front matter
│ ├── *.md # Markdown files with YAML front matter
│ ├── daily/ # Daily notes (YYYY-MM-DD.md)
│ ├── .favorites.json # Favorites list (auto-generated)
│ └── daily-note-template.md # Optional daily note template
├── docs/ # Documentation
│ ├── KEYBOARD_SHORTCUTS.md # Keyboard shortcuts reference
│ ├── DAILY_NOTES.md # Daily notes guide
│ ├── USAGE_GUIDE.md # Complete usage guide
│ └── FREEBSD_BUILD.md # FreeBSD build guide
├── go.mod # Go dependencies
├── go.sum
├── API.md # REST API documentation
└── CLAUDE.md # This file
```
@ -602,15 +805,26 @@ project-notes/
**Backend Development**:
- `cmd/server/main.go` - Server initialization and routing
- `internal/api/handler.go` - API endpoints and request handling
- `internal/api/handler.go` - Main HTML endpoints and request handling
- `internal/api/rest_handler.go` - REST API v1 endpoints
- `internal/api/daily_notes.go` - Daily notes and calendar functionality
- `internal/api/favorites.go` - Favorites management
- `internal/indexer/indexer.go` - Search and indexing logic
- `internal/watcher/watcher.go` - Filesystem monitoring
**Frontend Development**:
- `frontend/src/editor.js` - CodeMirror editor, preview, slash commands
- `frontend/src/vim-mode-manager.js` - Vim mode integration
- `frontend/src/search.js` - Search modal functionality
- `frontend/src/link-inserter.js` - Note linking modal for `/link` command
- `frontend/src/file-tree.js` - File tree interactions and drag-and-drop
- `frontend/src/favorites.js` - Favorites system
- `frontend/src/daily-notes.js` - Daily notes creation and calendar widget
- `frontend/src/keyboard-shortcuts.js` - Global keyboard shortcuts
- `frontend/src/theme-manager.js` - Theme switching logic
- `frontend/src/font-manager.js` - Font customization logic
- `frontend/src/ui.js` - UI utilities (sidebar toggle)
- `static/theme.css` - Styling and theming
- `static/theme.css` - Styling and theming (8 themes)
- `templates/*.html` - HTML templates (Go template syntax)
**Configuration**: