Upgrade Readme

2025-11-11 17:05:26 +01:00
parent 1d5a0fb39b
commit b0cbee453e
4 changed files with 957 additions and 189 deletions
--- a/docs/USAGE_GUIDE.md
+++ b/docs/USAGE_GUIDE.md
@ -0,0 +1,542 @@
+# Usage Guide
+
+Complete guide for using Project Notes - from creating your first note to advanced features.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Daily Notes](#daily-notes)
+- [Creating & Editing Notes](#creating--editing-notes)
+- [Searching Notes](#searching-notes)
+- [Organizing with Folders](#organizing-with-folders)
+- [Favorites System](#favorites-system)
+- [Slash Commands](#slash-commands)
+- [Customization & Settings](#customization--settings)
+- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Tips & Tricks](#tips--tricks)
+
+---
+
+## Quick Start
+
+The fastest way to get started with Project Notes:
+
+1. **Open the application** at `http://localhost:8080`
+2. **Press `Ctrl/Cmd+D`** to create today's daily note
+3. **Start writing** - the editor saves automatically with `Ctrl/Cmd+S`
+4. **Press `Ctrl/Cmd+K`** to search your notes anytime
+
+That's it! You're now using Project Notes.
+
+---
+
+## Daily Notes
+
+Daily notes are the **fastest way** to capture thoughts, tasks, and reflections.
+
+### Creating Today's Note
+
+**Option 1: Keyboard Shortcut** (Fastest)
+- Press **`Ctrl/Cmd+D`** anywhere in the application
+
+**Option 2: Header Button**
+- Click "📅 Note du jour" in the header
+
+**Option 3: Calendar**
+- Click the calendar icon
+- Click on today's date
+
+### Using the Calendar
+
+Navigate and access daily notes with the interactive calendar:
+
+- **Navigate months**: Use `‹` and `›` arrows
+- **Select a date**: Click any date to open/create that day's note
+- **Visual indicators**: Blue dots (●) show existing notes
+- **Quick access**: "Récentes" tab shows the last 7 days
+
+### Daily Note Template
+
+Each daily note is created with a structured template:
+
+```markdown
+---
+title: Notes du DD/MM/YYYY
+date: YYYY-MM-DD
+last_modified: YYYY-MM-DD:HH:MM
+tags:
+  - daily
+---
+
+# Notes du DD/MM/YYYY
+
+## 🎯 Objectifs
+- 
+
+## 📝 Notes
+
+
+## ✅ Accompli
+- 
+
+## 💭 Réflexions
+
+
+## 🔗 Liens
+- 
+```
+
+**Customize your template** in `docs/DAILY_NOTES.md`
+
+---
+
+## Creating & Editing Notes
+
+### Creating a New Note
+
+**Method 1: Header Button**
+1. Click "✨ Nouvelle note" in the header
+2. Enter a filename (e.g., `my-note.md` or `folder/my-note.md`)
+3. Click "Créer / Ouvrir"
+
+**Method 2: Keyboard Shortcut**
+- Press **`Ctrl/Cmd+N`** to open the create dialog
+
+**Method 3: In a Folder**
+1. Navigate to a folder in the sidebar
+2. Click the folder's action button
+3. Create note directly in that folder
+
+### Note Structure
+
+Every note includes YAML front matter:
+
+```markdown
+---
+title: My Note Title
+date: 2025-11-11
+last_modified: 2025-11-11:14:30
+tags:
+  - tag1
+  - tag2
+---
+
+# Content starts here
+
+Your Markdown content...
+```
+
+**Front matter is automatic**:
+- `title`: Extracted from first heading or filename
+- `date`: Creation date (never changes)
+- `last_modified`: Updated on every save
+- `tags`: For organizing and searching
+
+### Editing a Note
+
+1. **Open a note**: Click it in the sidebar file tree
+2. **Edit in left pane**: Use the CodeMirror editor
+3. **See live preview**: Right pane updates in real-time
+4. **Save changes**: Click "Enregistrer" or press **`Ctrl/Cmd+S`**
+
+**Editor features**:
+- Syntax highlighting for Markdown
+- Line numbers
+- Auto-closing brackets
+- Optional Vim mode
+- Slash commands (type `/`)
+
+### Deleting a Note
+
+1. Open the note you want to delete
+2. Click the "Supprimer" button
+3. Confirm the deletion
+
+**⚠️ Warning**: Deletion is permanent and immediate.
+
+---
+
+## Searching Notes
+
+Project Notes includes a powerful search system with two interfaces.
+
+### Quick Search Modal (Recommended)
+
+**Open the modal**:
+- Press **`Ctrl/Cmd+K`** anywhere
+- Results appear instantly as you type
+
+**Navigate results**:
+- `↑` / `↓` - Move between results
+- `Enter` - Open selected note
+- `Esc` - Close modal
+
+### Search Syntax
+
+Both search interfaces support advanced syntax:
+
+#### General Search
+Type keywords to search across:
+- Note titles
+- Tags
+- File paths
+- Note content
+
+**Example**: `meeting backend` finds notes containing both words
+
+#### Tag Filter
+Use `tag:name` to filter by specific tags.
+
+**Examples**:
+- `tag:projet` - All notes tagged "projet"
+- `tag:urgent tag:work` - Notes with both tags
+
+#### Title Filter
+Use `title:keyword` to search only in titles.
+
+**Examples**:
+- `title:meeting` - Notes with "meeting" in title
+- `title:"daily standup"` - Exact phrase in title
+
+#### Path Filter
+Use `path:folder` to search by file path.
+
+**Examples**:
+- `path:backend` - Notes in backend folder
+- `path:projets/frontend` - Specific subfolder
+
+#### Quoted Phrases
+Use `"exact phrase"` for exact matches.
+
+**Example**: `"database migration"` finds that exact phrase
+
+#### Combined Queries
+Mix syntax for powerful searches:
+
+```
+tag:projet path:backend "API design"
+```
+Finds notes tagged "projet", in the backend folder, containing "API design"
+
+### Search Results
+
+Results are **scored and ranked** by relevance:
+- **Title matches** score highest
+- **Tag matches** score high
+- **Path matches** score medium
+- **Content matches** score lower
+
+This ensures the most relevant notes appear first.
+
+---
+
+## Organizing with Folders
+
+### Creating Folders
+
+**Method 1: Sidebar Button**
+1. Click "📁 Nouveau dossier" at bottom of sidebar
+2. Enter folder path (e.g., `projets` or `work/meetings`)
+3. Press Enter
+
+**Method 2: Keyboard Shortcut**
+- Press **`Ctrl/Cmd+Shift+F`** to open folder dialog
+
+**Method 3: Create with Note**
+- When creating a note, include folder in path: `folder/note.md`
+- The folder is created automatically
+
+### Folder Structure
+
+Organize notes hierarchically:
+
+```
+notes/
+├── daily/
+│   └── 2025/
+│       └── 11/
+│           └── 11.md
+├── projets/
+│   ├── backend/
+│   │   ├── api-design.md
+│   │   └── database.md
+│   └── frontend/
+│       └── ui-components.md
+└── meetings/
+    └── weekly-standup.md
+```
+
+### Moving Notes Between Folders
+
+**Drag and drop** notes in the file tree:
+1. Click and hold a note
+2. Drag to target folder
+3. Release to move
+
+**Or rename with path**:
+1. Edit the note's front matter
+2. Change the path in the filename
+3. Save the note
+
+---
+
+## Favorites System
+
+Star important notes and folders for **quick access**.
+
+### Adding to Favorites
+
+1. **Hover** over any note or folder in the sidebar
+2. **Click the ★ icon** that appears
+3. The item is added to "⭐ Favoris" section
+
+### Accessing Favorites
+
+- **Sidebar section**: All favorites appear under "⭐ Favoris"
+- **Expandable folders**: Click folders to see their contents
+- **Quick access**: Always visible at top of sidebar
+
+### Managing Favorites
+
+- **Remove from favorites**: Click the ★ icon again
+- **Persistence**: Favorites are saved to `.favorites.json`
+- **Sync**: Copy `.favorites.json` to sync across machines
+
+---
+
+## Slash Commands
+
+Insert common Markdown elements quickly with `/` commands.
+
+### Using Slash Commands
+
+1. **Type `/`** at the start of a line in the editor
+2. **Command palette appears** with available commands
+3. **Filter by typing**: e.g., `/h1`, `/table`
+4. **Select command**: Use `↑`/`↓` and `Enter` or `Tab`
+5. **Snippet inserted** at cursor position
+
+### Available Commands
+
+| Command | Description | Output |
+|---------|-------------|--------|
+| `/h1` | Heading 1 | `# Heading` |
+| `/h2` | Heading 2 | `## Heading` |
+| `/h3` | Heading 3 | `### Heading` |
+| `/list` | Bullet list | `- Item` |
+| `/date` | Current date | `2025-11-11` |
+| `/link` | Link | `[text](url)` |
+| `/bold` | Bold text | `**bold**` |
+| `/italic` | Italic text | `*italic*` |
+| `/code` | Inline code | `` `code` `` |
+| `/codeblock` | Code block | ` ```\ncode\n``` ` |
+| `/quote` | Blockquote | `> Quote` |
+| `/hr` | Horizontal rule | `---` |
+| `/table` | Table | Full table template |
+
+### Custom Commands
+
+Slash commands are defined in `frontend/src/editor.js`. 
+
+Add your own by editing the `slashCommands` array:
+
+```javascript
+{ 
+  trigger: '/mycommand', 
+  description: 'My custom command',
+  template: 'Your template here'
+}
+```
+
+---
+
+## Customization & Settings
+
+Access settings by clicking **⚙️ Paramètres** in the sidebar.
+
+### Theme Selection
+
+Choose from **8 dark themes**:
+
+1. **Material Dark** (default) - Professional Material Design
+2. **Monokai Dark** - Classic Monokai colors
+3. **Dracula** - Elegant purple and cyan
+4. **One Dark** - Popular Atom theme
+5. **Solarized Dark** - Scientifically optimized
+6. **Nord** - Arctic blue tones
+7. **Catppuccin** - Pastel comfort palette
+8. **Everforest** - Nature-inspired greens
+
+**Changing theme**:
+1. Open Settings (⚙️)
+2. Select "Thèmes" tab
+3. Click your preferred theme
+4. Theme applies instantly
+
+### Font Customization
+
+#### Font Family
+
+Choose from **8 fonts**:
+
+- **JetBrains Mono** (default) - Designed for IDEs
+- **Fira Code** - Popular with ligatures
+- **Inter** - Clean and professional
+- **Poppins** - Modern sans-serif
+- **Public Sans** - Government-approved readability
+- **Cascadia Code** - Microsoft's coding font
+- **Source Code Pro** - Adobe's classic
+- **Sans-serif** - System fallback
+
+#### Font Size
+
+Choose from **4 sizes**:
+
+- **Small** (14px) - Compact view
+- **Medium** (16px) - Default comfortable reading
+- **Large** (18px) - Enhanced readability
+- **X-Large** (20px) - Maximum comfort
+
+**Changing font/size**:
+1. Open Settings (⚙️)
+2. Select "Polices" tab
+3. Choose font family and size
+4. Changes apply instantly
+
+### Editor Settings
+
+#### Vim Mode
+
+Enable **full Vim keybindings** in the editor:
+
+**Features**:
+- hjkl navigation
+- Insert, Normal, and Visual modes
+- All standard Vim commands (dd, yy, p, u, etc.)
+- Vim motions (w, b, $, 0, gg, G, etc.)
+- Search with `/` and `?`
+- Command mode with `:`
+
+**Enabling Vim mode**:
+1. Open Settings (⚙️)
+2. Select "Éditeur" tab
+3. Toggle "Mode Vim" switch
+4. Editor reloads with Vim keybindings
+
+**Note**: Requires `@replit/codemirror-vim` package (installed with `npm install`).
+
+---
+
+## Keyboard Shortcuts
+
+Global shortcuts work **anywhere** in the application (except when typing in input fields).
+
+### Complete Shortcut List
+
+| Shortcut | Action | Context |
+|----------|--------|---------|
+| `Ctrl/Cmd+K` | Open search modal | Global |
+| `Ctrl/Cmd+S` | Save current note | Editor |
+| `Ctrl/Cmd+D` | Open today's daily note | Global |
+| `Ctrl/Cmd+N` | Create new note | Global |
+| `Ctrl/Cmd+H` | Go to homepage | Global |
+| `Ctrl/Cmd+B` | Toggle sidebar | Global |
+| `Ctrl/Cmd+,` | Open settings | Global |
+| `Ctrl/Cmd+P` | Toggle preview pane | Editor |
+| `Ctrl/Cmd+Shift+F` | Create new folder | Global |
+| `Escape` | Close any modal | Modals |
+
+### Platform Notes
+
+- **macOS**: Use `Cmd` (⌘)
+- **Windows/Linux/FreeBSD**: Use `Ctrl`
+
+### Viewing Shortcuts
+
+Access the shortcuts reference:
+- Press `Ctrl/Cmd+K` to see search shortcuts
+- Click **ℹ️ button** in sidebar for the About page
+- See full list with descriptions and contexts
+
+**Complete documentation**: [docs/KEYBOARD_SHORTCUTS.md](./KEYBOARD_SHORTCUTS.md)
+
+---
+
+## Tips & Tricks
+
+### Productivity Tips
+
+1. **Daily notes habit**: Press `Ctrl/Cmd+D` every morning
+2. **Tag consistently**: Use consistent tags for better search
+3. **Favorite often**: Star notes you reference frequently
+4. **Use slash commands**: Speed up formatting with `/`
+5. **Master search syntax**: Learn `tag:`, `title:`, `path:` filters
+6. **Keyboard-driven**: Use shortcuts instead of clicking
+
+### Organization Best Practices
+
+1. **Folder structure**: Organize by project/area, not date
+2. **Daily notes separate**: Keep daily notes in `daily/YYYY/MM/` structure
+3. **Meaningful names**: Use descriptive filenames
+4. **Consistent tags**: Create a tag system and stick to it
+5. **Regular cleanup**: Archive or delete outdated notes
+
+### Advanced Workflows
+
+#### Meeting Notes Template
+1. Create folder: `meetings/`
+2. Use consistent naming: `YYYY-MM-DD-meeting-name.md`
+3. Tag with participants: `tag:john tag:sarah`
+4. Link to related notes in content
+
+#### Project Documentation
+1. Folder per project: `projets/project-name/`
+2. Index note: `index.md` with links to all docs
+3. Subfolders: `backend/`, `frontend/`, `design/`
+4. Cross-reference with `[link](../other-project/doc.md)`
+
+#### Knowledge Base
+1. Main categories as folders
+2. Index notes with tables of contents
+3. Liberal use of tags for cross-cutting topics
+4. Regular review and updates
+
+### Vim Mode Tips
+
+If using Vim mode:
+- `i` to enter insert mode
+- `Esc` to return to normal mode
+- `:w` to save (or `Ctrl/Cmd+S`)
+- `dd` to delete line
+- `yy` to copy line
+- `/search` to find text
+
+### Backup Strategy
+
+1. **Git repository**: Initialize Git in `notes/` directory
+2. **Automated commits**: Cron job to commit changes daily
+3. **Remote backup**: Push to GitHub/GitLab
+4. **Export via API**: Use REST API to backup programmatically
+
+Example backup script:
+```bash
+#!/bin/bash
+cd ~/project-notes/notes
+git add .
+git commit -m "Auto backup $(date)"
+git push origin main
+```
+
+---
+
+## Need Help?
+
+- **Documentation**: See [README.md](../README.md) for overview
+- **API Guide**: See [API.md](../API.md) for REST API
+- **Daily Notes**: See [DAILY_NOTES.md](./DAILY_NOTES.md) for customization
+- **Architecture**: See [ARCHITECTURE_OVERVIEW.md](./ARCHITECTURE_OVERVIEW.md)
+- **Keyboard Shortcuts**: See [KEYBOARD_SHORTCUTS.md](./KEYBOARD_SHORTCUTS.md)
+
+---
+
+**Last updated**: November 11, 2025