Upgrade Readme
This commit is contained in:
@ -5,7 +5,11 @@
|
||||
"Bash(kill:*)",
|
||||
"Bash(go run:*)",
|
||||
"Bash(lsof:*)",
|
||||
"Bash(npm run build:*)"
|
||||
"Bash(npm run build:*)",
|
||||
"Bash(go build:*)",
|
||||
"Bash(/home/mathieu/git/project-notes/notes/test-delete-1.md)",
|
||||
"Bash(/home/mathieu/git/project-notes/notes/test-delete-2.md)",
|
||||
"Bash(/home/mathieu/git/project-notes/notes/test-delete-folder/test.md)"
|
||||
],
|
||||
"deny": [],
|
||||
"ask": []
|
||||
|
||||
237
README.md
237
README.md
@ -3,13 +3,15 @@
|
||||
A lightweight, web-based Markdown note-taking application with a Go backend and a minimalist frontend built with htmx.
|
||||
|
||||
- 🚫 No database
|
||||
- 📝 Pure Markdown with flat files
|
||||
- 🔒 Your notes, your server
|
||||
- 📝 Fat files : Markdown with frontmatters
|
||||
- 🔒 Your notes, your application, your server, your data
|
||||
- ⌨️ Vim Mode
|
||||
- 🎹 Keyboard driven
|
||||
- 🔍 Powerful Search
|
||||
- 🌍 Run everywhere (Linux & FreeBSD)
|
||||
- 🛠️ Easy to build
|
||||
- 🚀 Powerful API
|
||||
- 📱 Responsive with laptop and smartphone
|
||||
- 🛠️ Super Easy to build
|
||||
- 🚀 A powerful API
|
||||
|
||||
|
||||
## Features
|
||||
@ -50,25 +52,21 @@ A lightweight, web-based Markdown note-taking application with a Go backend and
|
||||
* [Highlight.js](https://highlightjs.org/): For syntax highlighting in code blocks.
|
||||
* Custom CSS theme with dark mode inspired by VS Code and GitHub Dark.
|
||||
|
||||
## Architecture
|
||||
## Documentation
|
||||
|
||||
Project Notes 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**: CodeMirror 6, drag-and-drop, and UI enhancements
|
||||
- **Vite**: Modern build tool for efficient JavaScript bundling
|
||||
**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
|
||||
|
||||
**Key Design Principles**:
|
||||
- Server renders HTML, not JSON (simpler, faster)
|
||||
- HTMX handles all AJAX and DOM updates (consistent, reliable)
|
||||
- JavaScript enhances UI (editor, drag-and-drop, animations)
|
||||
- Event-driven coordination between HTMX and JavaScript
|
||||
**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
|
||||
|
||||
For detailed documentation, see:
|
||||
- **[docs/DAILY_NOTES.md](./docs/DAILY_NOTES.md)** - Complete daily notes guide and customization
|
||||
**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
|
||||
- **[API.md](./API.md)** - REST API documentation
|
||||
- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and release notes
|
||||
|
||||
## Getting Started
|
||||
@ -136,194 +134,57 @@ go build -o server ./cmd/server
|
||||
./server
|
||||
```
|
||||
|
||||
## Usage
|
||||
## Quick Start Guide
|
||||
|
||||
### Daily Notes (Quick Start)
|
||||
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
|
||||
|
||||
**The fastest way to start taking notes:**
|
||||
**→ Complete usage guide**: [docs/USAGE_GUIDE.md](./docs/USAGE_GUIDE.md)
|
||||
|
||||
1. Press **`Ctrl/Cmd+D`** or click "📅 Note du jour" in the header
|
||||
2. A note for today is automatically created with a structured template
|
||||
3. Start writing in sections: Objectifs, Notes, Accompli, Réflexions, Liens
|
||||
## Key Features at a Glance
|
||||
|
||||
**Using the Calendar:**
|
||||
- Navigate months with `‹` and `›` arrows
|
||||
- Click any date to open/create that day's note
|
||||
- Blue dots (●) indicate existing notes
|
||||
- Check "Récentes" for quick access to the last 7 days
|
||||
|
||||
For complete daily notes documentation, see **[docs/DAILY_NOTES.md](./docs/DAILY_NOTES.md)**
|
||||
|
||||
### 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
|
||||
|
||||
**Quick Search Modal** (Recommended):
|
||||
1. Press **`Ctrl/Cmd+K`** anywhere to open the search modal.
|
||||
2. Type your query - results appear instantly with keyboard navigation.
|
||||
3. Use **`↑`/`↓`** to navigate, **`Enter`** to open, **`Esc`** to close.
|
||||
|
||||
**Search Syntax** (works in both modal and header search):
|
||||
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
|
||||
|
||||
### Customization & Settings
|
||||
|
||||
Access settings by clicking the **⚙️ Paramètres** button in the sidebar.
|
||||
|
||||
**Theme Selection** (8 options):
|
||||
- Material Dark (default) - Professional Material Design theme
|
||||
- Monokai Dark - Classic Monokai palette
|
||||
- Dracula - Elegant purple and cyan accents
|
||||
- One Dark - Popular Atom theme
|
||||
- Solarized Dark - Scientifically optimized colors
|
||||
- Nord - Arctic blue-toned theme
|
||||
- Catppuccin - Pastel comfort palette
|
||||
- Everforest - Nature-inspired green and beige
|
||||
|
||||
**Font Customization**:
|
||||
- **Fonts**: JetBrains Mono (default), Fira Code, Inter, Poppins, Public Sans, Cascadia Code, Source Code Pro, Sans-serif
|
||||
- **Sizes**: Small (14px), Medium (16px), Large (18px), X-Large (20px)
|
||||
|
||||
**Editor Settings**:
|
||||
- **Vim Mode**: Enable full Vim keybindings in CodeMirror
|
||||
- hjkl navigation, insert/normal/visual modes
|
||||
- All standard Vim commands and motions
|
||||
- Requires `@replit/codemirror-vim` package
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
Press `Ctrl/Cmd+K` or visit the **About** page (ℹ️ button in sidebar) for the complete list:
|
||||
|
||||
- `Ctrl/Cmd+K` - Open search
|
||||
- `Ctrl/Cmd+S` - Save note
|
||||
- `Ctrl/Cmd+D` - Open daily note
|
||||
- `Ctrl/Cmd+N` - Create new note
|
||||
- `Ctrl/Cmd+H` - Go home
|
||||
- `Ctrl/Cmd+B` - Toggle sidebar
|
||||
- `Ctrl/Cmd+,` - Open settings
|
||||
- `Ctrl/Cmd+P` - Toggle preview
|
||||
- `Ctrl/Cmd+Shift+F` - Create new folder
|
||||
- `Escape` - Close modals
|
||||
|
||||
### Favorites System
|
||||
|
||||
Star important notes and folders for quick access:
|
||||
|
||||
1. Hover over any note or folder in the sidebar
|
||||
2. Click the **★** icon to add/remove from favorites
|
||||
3. Access favorites from the **⭐ Favoris** section in the sidebar
|
||||
4. Favorites persist across sessions (stored in `.favorites.json`)
|
||||
|
||||
### 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
|
||||
|
||||
The server accepts the following command-line flags:
|
||||
|
||||
- `-addr :PORT` - Change server address (default: `:8080`)
|
||||
- `-notes-dir PATH` - Change notes directory (default: `./notes`)
|
||||
|
||||
Example:
|
||||
```bash
|
||||
go run ./cmd/server -addr :3000 -notes-dir ~/my-notes
|
||||
```
|
||||
- **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
|
||||
|
||||
Project Notes includes a full REST API for programmatic access to your notes.
|
||||
Full REST API for programmatic access:
|
||||
|
||||
**Base URL**: `http://localhost:8080/api/v1`
|
||||
|
||||
### Quick Examples
|
||||
|
||||
**List all notes**:
|
||||
```bash
|
||||
# List all notes
|
||||
curl http://localhost:8080/api/v1/notes
|
||||
```
|
||||
|
||||
**Get a specific note** (JSON):
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/notes/projet/backend.md
|
||||
```
|
||||
# Get a note (JSON or Markdown)
|
||||
curl http://localhost:8080/api/v1/notes/path/to/note.md
|
||||
|
||||
**Get note as Markdown**:
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/notes/projet/backend.md \
|
||||
-H "Accept: text/markdown"
|
||||
```
|
||||
|
||||
**Create/Update a note**:
|
||||
```bash
|
||||
curl -X PUT http://localhost:8080/api/v1/notes/test.md \
|
||||
# Create/update a note
|
||||
curl -X PUT http://localhost:8080/api/v1/notes/new-note.md \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"body": "\n# Test\n\nContent here...",
|
||||
"frontMatter": {
|
||||
"title": "Test Note",
|
||||
"tags": ["test"]
|
||||
}
|
||||
}'
|
||||
```
|
||||
-d '{"body": "# Content", "frontMatter": {"title": "Title"}}'
|
||||
|
||||
**Delete a note**:
|
||||
```bash
|
||||
# Delete a note
|
||||
curl -X DELETE http://localhost:8080/api/v1/notes/old-note.md
|
||||
```
|
||||
|
||||
### Full API Documentation
|
||||
**→ Complete API documentation**: [API.md](./API.md)
|
||||
|
||||
See **[API.md](./API.md)** for complete documentation including:
|
||||
- All endpoints (LIST, GET, PUT, DELETE)
|
||||
- Request/response formats
|
||||
- Content negotiation (JSON/Markdown)
|
||||
- Advanced examples (sync, backup, automation)
|
||||
- Integration guides
|
||||
## Server Configuration
|
||||
|
||||
### Use Cases
|
||||
```bash
|
||||
# Custom port
|
||||
go run ./cmd/server -addr :3000
|
||||
|
||||
- **Backup**: Automate note backups with cron jobs
|
||||
- **Sync**: Synchronize notes across machines
|
||||
- **Integration**: Connect with other tools (Obsidian, Notion, etc.)
|
||||
- **Automation**: Create notes programmatically (daily notes, templates)
|
||||
- **CI/CD**: Validate Markdown in pipelines
|
||||
# Custom notes directory
|
||||
go run ./cmd/server -notes-dir ~/my-notes
|
||||
|
||||
**⚠️ Security Note**: The API currently has no authentication. Use a reverse proxy (nginx, Caddy) with auth if exposing publicly.
|
||||
# Both
|
||||
go run ./cmd/server -addr :3000 -notes-dir ~/my-notes
|
||||
```
|
||||
|
||||
361
docs/ARCHITECTURE_OVERVIEW.md
Normal file
361
docs/ARCHITECTURE_OVERVIEW.md
Normal file
@ -0,0 +1,361 @@
|
||||
# Architecture Overview
|
||||
|
||||
## Hybrid Architecture
|
||||
|
||||
Project Notes uses a **hybrid architecture** that combines the best of multiple paradigms:
|
||||
|
||||
### Core Components
|
||||
|
||||
- **Go Backend**: Fast, type-safe server handling file operations and indexing
|
||||
- **HTMX**: "HTML over the wire" for dynamic interactions with minimal JavaScript
|
||||
- **Modern JavaScript**: CodeMirror 6, drag-and-drop, and UI enhancements
|
||||
- **Vite**: Modern build tool for efficient JavaScript bundling
|
||||
|
||||
### Key Design Principles
|
||||
|
||||
1. **Server renders HTML, not JSON** (simpler, faster)
|
||||
2. **HTMX handles all AJAX and DOM updates** (consistent, reliable)
|
||||
3. **JavaScript enhances UI** (editor, drag-and-drop, animations)
|
||||
4. **Event-driven coordination** between HTMX and JavaScript
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### 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
|
||||
- **Chi Router**: Lightweight, fast HTTP router (implied by usage)
|
||||
|
||||
**Why Go?**
|
||||
- Fast compilation and execution
|
||||
- Excellent standard library
|
||||
- Built-in concurrency
|
||||
- Single binary deployment
|
||||
- Cross-platform support (Linux, FreeBSD, macOS, Windows)
|
||||
|
||||
### Frontend: HTML, CSS, JavaScript
|
||||
|
||||
#### Core Technologies
|
||||
|
||||
- **[htmx](https://htmx.org/)**: For dynamic UI interactions without writing much JavaScript
|
||||
- Declarative AJAX requests
|
||||
- DOM swapping and updates
|
||||
- WebSocket support
|
||||
- Event-driven architecture
|
||||
|
||||
- **[CodeMirror 6](https://codemirror.net/6/)**: For the robust Markdown editor
|
||||
- Extensible architecture
|
||||
- Syntax highlighting
|
||||
- Vim mode support
|
||||
- Custom extensions (slash commands)
|
||||
|
||||
- **[Vite](https://vitejs.dev/)**: For bundling frontend JavaScript modules
|
||||
- Fast development server
|
||||
- Optimized production builds
|
||||
- ES modules support
|
||||
- Hot module replacement
|
||||
|
||||
#### Supporting Libraries
|
||||
|
||||
- **[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**: Dark mode inspired by VS Code and GitHub Dark
|
||||
|
||||
**Why This Stack?**
|
||||
- Minimal JavaScript complexity
|
||||
- Progressive enhancement
|
||||
- Fast page loads
|
||||
- SEO-friendly (server-rendered HTML)
|
||||
- Easy to understand and maintain
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Server-Side Rendering (SSR)
|
||||
|
||||
All HTML is rendered on the server using Go's `html/template` package:
|
||||
- Initial page loads are fast
|
||||
- No JavaScript required for basic functionality
|
||||
- Better SEO and accessibility
|
||||
|
||||
### Progressive Enhancement
|
||||
|
||||
The application works without JavaScript but is enhanced with it:
|
||||
1. **Base functionality**: Browse notes, view content (no JS)
|
||||
2. **HTMX enhancement**: Dynamic updates without page reloads
|
||||
3. **JavaScript enhancement**: Rich editor, drag-and-drop, animations
|
||||
|
||||
### File-Based Storage
|
||||
|
||||
Notes are stored as plain Markdown files with YAML front matter:
|
||||
```markdown
|
||||
---
|
||||
title: My Note
|
||||
date: 2025-11-11
|
||||
last_modified: 2025-11-11:14:30
|
||||
tags:
|
||||
- example
|
||||
- markdown
|
||||
---
|
||||
|
||||
# My Note
|
||||
|
||||
Content here...
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- No database setup required
|
||||
- Easy backups (just copy files)
|
||||
- Version control friendly (Git)
|
||||
- Human-readable
|
||||
- Portable (works with any Markdown tool)
|
||||
|
||||
### In-Memory Indexing
|
||||
|
||||
Notes are indexed in memory for fast search:
|
||||
- Full-text search across title, tags, path, content
|
||||
- Tag-based filtering
|
||||
- Path-based navigation
|
||||
- Real-time updates via file system watcher
|
||||
|
||||
**Trade-offs**:
|
||||
- Memory usage scales with note count
|
||||
- Index rebuilt on server restart
|
||||
- Suitable for personal/small team use (< 10,000 notes)
|
||||
|
||||
## Request Flow
|
||||
|
||||
### Reading a Note
|
||||
|
||||
```
|
||||
Browser → GET /editor?note=path/to/note.md
|
||||
↓
|
||||
Go Handler
|
||||
↓
|
||||
Read file from disk
|
||||
↓
|
||||
Parse front matter
|
||||
↓
|
||||
Render HTML template
|
||||
↓
|
||||
Browser ← HTML response
|
||||
↓
|
||||
CodeMirror initializes
|
||||
↓
|
||||
User sees editable note
|
||||
```
|
||||
|
||||
### Saving a Note
|
||||
|
||||
```
|
||||
Browser → htmx POST /save
|
||||
↓
|
||||
Go Handler
|
||||
↓
|
||||
Update front matter (last_modified)
|
||||
↓
|
||||
Write file to disk
|
||||
↓
|
||||
File system watcher detects change
|
||||
↓
|
||||
Re-index note
|
||||
↓
|
||||
Browser ← Success response
|
||||
↓
|
||||
htmx updates UI
|
||||
```
|
||||
|
||||
### Search
|
||||
|
||||
```
|
||||
Browser → htmx GET /search?q=query
|
||||
↓
|
||||
Go Handler
|
||||
↓
|
||||
Query in-memory index
|
||||
↓
|
||||
Score and rank results
|
||||
↓
|
||||
Render search results template
|
||||
↓
|
||||
Browser ← HTML fragment
|
||||
↓
|
||||
htmx swaps into DOM
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
Filesystem (notes/) ←→ File Watcher (fsnotify)
|
||||
↓
|
||||
Indexer (in-memory)
|
||||
↓
|
||||
HTTP Handlers
|
||||
↓
|
||||
Templates + HTMX
|
||||
↓
|
||||
Browser
|
||||
↓
|
||||
CodeMirror Editor
|
||||
```
|
||||
|
||||
## Scalability Considerations
|
||||
|
||||
### Current Design (Suitable for)
|
||||
|
||||
- Personal use: 1-10,000 notes
|
||||
- Small teams: 2-5 users
|
||||
- Single server deployment
|
||||
- Notes up to ~1MB each
|
||||
|
||||
### Limitations
|
||||
|
||||
- **No concurrent editing**: Last write wins
|
||||
- **In-memory index**: Limited by server RAM
|
||||
- **No authentication**: Requires reverse proxy
|
||||
- **Single server**: No horizontal scaling
|
||||
|
||||
### Future Enhancements (if needed)
|
||||
|
||||
- SQLite for metadata indexing (larger note collections)
|
||||
- WebSocket for real-time collaboration
|
||||
- JWT authentication built-in
|
||||
- Redis for distributed caching
|
||||
- Object storage for large attachments
|
||||
|
||||
## Security Model
|
||||
|
||||
### Current State
|
||||
|
||||
- **No built-in authentication**: Designed for local/private networks
|
||||
- **XSS protection**: DOMPurify sanitizes Markdown output
|
||||
- **Path traversal prevention**: Input validation on file paths
|
||||
- **CSRF**: Not needed (no session-based auth)
|
||||
|
||||
### Recommended Production Setup
|
||||
|
||||
```
|
||||
Internet → Reverse Proxy (nginx/Caddy)
|
||||
↓
|
||||
Basic Auth / OAuth
|
||||
↓
|
||||
Project Notes (Go)
|
||||
↓
|
||||
Filesystem (notes/)
|
||||
```
|
||||
|
||||
Example nginx config:
|
||||
```nginx
|
||||
location / {
|
||||
auth_basic "Project Notes";
|
||||
auth_basic_user_file /etc/nginx/.htpasswd;
|
||||
proxy_pass http://localhost:8080;
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### Strengths
|
||||
|
||||
- **Fast page loads**: Server-rendered HTML
|
||||
- **Low latency**: In-memory indexing
|
||||
- **Efficient search**: Pre-indexed content
|
||||
- **Small footprint**: ~10-20MB RAM for typical usage
|
||||
|
||||
### Benchmarks (approximate)
|
||||
|
||||
- Note load time: < 50ms
|
||||
- Search query: < 10ms (1000 notes)
|
||||
- Save operation: < 100ms
|
||||
- Index rebuild: < 1s (1000 notes)
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Backend Development
|
||||
|
||||
```bash
|
||||
# Run with auto-reload (using air or similar)
|
||||
air
|
||||
|
||||
# Or manual reload
|
||||
go run ./cmd/server
|
||||
```
|
||||
|
||||
### Frontend Development
|
||||
|
||||
```bash
|
||||
# Watch mode (auto-rebuild)
|
||||
cd frontend
|
||||
npm run build -- --watch
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
go test ./...
|
||||
|
||||
# With coverage
|
||||
go test -cover ./...
|
||||
|
||||
# Specific package
|
||||
go test -v ./internal/indexer
|
||||
```
|
||||
|
||||
## Deployment Options
|
||||
|
||||
### 1. Simple Binary
|
||||
|
||||
```bash
|
||||
# Build
|
||||
go build -o server ./cmd/server
|
||||
|
||||
# Run
|
||||
./server -addr :8080 -notes-dir ~/notes
|
||||
```
|
||||
|
||||
### 2. Systemd Service (Linux)
|
||||
|
||||
See [FREEBSD_BUILD.md](./FREEBSD_BUILD.md) for service examples.
|
||||
|
||||
### 3. Docker (future)
|
||||
|
||||
```dockerfile
|
||||
FROM golang:1.22 AS builder
|
||||
WORKDIR /app
|
||||
COPY . .
|
||||
RUN go build -o server ./cmd/server
|
||||
|
||||
FROM alpine:latest
|
||||
RUN apk add --no-cache ca-certificates
|
||||
COPY --from=builder /app/server /server
|
||||
COPY --from=builder /app/static /static
|
||||
COPY --from=builder /app/templates /templates
|
||||
EXPOSE 8080
|
||||
CMD ["/server"]
|
||||
```
|
||||
|
||||
### 4. Reverse Proxy
|
||||
|
||||
Always recommended for production:
|
||||
- nginx, Caddy, Traefik
|
||||
- TLS termination
|
||||
- Authentication
|
||||
- Rate limiting
|
||||
- Caching
|
||||
|
||||
## Documentation
|
||||
|
||||
For more detailed information, see:
|
||||
|
||||
- **[ARCHITECTURE.md](../ARCHITECTURE.md)** - Complete system architecture, patterns, and best practices
|
||||
- **[CLAUDE.md](../CLAUDE.md)** - Development guide and implementation details
|
||||
- **[API.md](../API.md)** - REST API documentation
|
||||
- **[DAILY_NOTES.md](./DAILY_NOTES.md)** - Daily notes feature guide
|
||||
- **[FREEBSD_BUILD.md](./FREEBSD_BUILD.md)** - FreeBSD deployment guide
|
||||
- **[CHANGELOG.md](../CHANGELOG.md)** - Version history
|
||||
|
||||
---
|
||||
|
||||
**Last updated**: November 11, 2025
|
||||
542
docs/USAGE_GUIDE.md
Normal file
542
docs/USAGE_GUIDE.md
Normal file
@ -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
|
||||
Reference in New Issue
Block a user