personotes/docs/USAGE_GUIDE.md

# Usage Guide

Complete guide for using PersoNotes - 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 PersoNotes:

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 PersoNotes.

---

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

PersoNotes 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