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

Upgrade Readme

Browse Source
This commit is contained in:
Mathieu Aumont
2025-11-11 17:05:26 +01:00
parent 1d5a0fb39b
commit b0cbee453e
4 changed files with 957 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
README.md
View File

@ -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
```