196 lines
4.6 KiB
Markdown
196 lines
4.6 KiB
Markdown
# Excalidraw Quick Start Guide
|
|
|
|
## ✅ What's Fixed
|
|
|
|
The Excalidraw implementation now fully supports Obsidian's format:
|
|
|
|
1. **✅ No more 400 errors** - Fixed URL encoding issues with special characters
|
|
2. **✅ LZ-String compression** - Correctly parses Obsidian's compressed-json format
|
|
3. **✅ Round-trip compatibility** - Files saved in ObsiViewer open perfectly in Obsidian
|
|
4. **✅ Front matter preservation** - Metadata and tags are maintained
|
|
5. **✅ Legacy support** - Old flat JSON files still work and auto-convert on save
|
|
|
|
## 🚀 Quick Test
|
|
|
|
### 1. Start the Server
|
|
|
|
```bash
|
|
npm install # Installs lz-string dependency
|
|
npm run dev # Start development server
|
|
```
|
|
|
|
### 2. Test with Existing File
|
|
|
|
A test file has been created at `vault/test-drawing.excalidraw.md`:
|
|
|
|
1. Open ObsiViewer in your browser
|
|
2. Navigate to the file list
|
|
3. Click on `test-drawing.excalidraw.md`
|
|
4. The Excalidraw editor should load without errors
|
|
|
|
### 3. Verify API Endpoints
|
|
|
|
Test the new query param API:
|
|
|
|
```bash
|
|
# GET file (should return JSON scene)
|
|
curl "http://localhost:4200/api/files?path=test-drawing.excalidraw.md"
|
|
|
|
# Should return:
|
|
# {
|
|
# "elements": [...],
|
|
# "appState": {...},
|
|
# "files": {...}
|
|
# }
|
|
```
|
|
|
|
### 4. Test Round-Trip
|
|
|
|
1. **Create in Obsidian**:
|
|
- Create a new Excalidraw drawing in Obsidian
|
|
- Draw some shapes
|
|
- Save the file
|
|
|
|
2. **Open in ObsiViewer**:
|
|
- Navigate to the file
|
|
- Verify it displays correctly
|
|
- Make some changes
|
|
- Save (Ctrl+S)
|
|
|
|
3. **Re-open in Obsidian**:
|
|
- Open the same file in Obsidian
|
|
- Verify all changes are preserved
|
|
- No warnings or errors should appear
|
|
|
|
## 🔧 Migration
|
|
|
|
If you have old flat JSON Excalidraw files:
|
|
|
|
```bash
|
|
# Preview what will be converted
|
|
npm run migrate:excalidraw:dry
|
|
|
|
# Apply migration
|
|
npm run migrate:excalidraw
|
|
```
|
|
|
|
This will:
|
|
- Convert `.excalidraw` and `.json` files to `.excalidraw.md`
|
|
- Use proper Obsidian format with LZ-String compression
|
|
- Create `.bak` backups of originals
|
|
- Skip files already in Obsidian format
|
|
|
|
## 🧪 Run Tests
|
|
|
|
```bash
|
|
# Backend unit tests (16 tests)
|
|
npm run test:excalidraw
|
|
|
|
# E2E tests
|
|
npm run test:e2e -- excalidraw.spec.ts
|
|
```
|
|
|
|
All tests should pass ✅
|
|
|
|
## 📝 Common Scenarios
|
|
|
|
### Opening a File with Spaces/Accents
|
|
|
|
**Before (❌ 400 error)**:
|
|
```
|
|
GET /api/files/Mon Dessin #1.excalidraw.md
|
|
```
|
|
|
|
**After (✅ works)**:
|
|
```
|
|
GET /api/files?path=Mon%20Dessin%20%231.excalidraw.md
|
|
```
|
|
|
|
The frontend now properly encodes paths.
|
|
|
|
### Saving a File
|
|
|
|
**Before (❌ saved as flat JSON)**:
|
|
```json
|
|
{
|
|
"elements": [],
|
|
"appState": {},
|
|
"files": {}
|
|
}
|
|
```
|
|
|
|
**After (✅ saved in Obsidian format)**:
|
|
```markdown
|
|
---
|
|
excalidraw-plugin: parsed
|
|
tags: [excalidraw]
|
|
---
|
|
# Excalidraw Data
|
|
## Drawing
|
|
```compressed-json
|
|
<LZ-String compressed data>
|
|
```
|
|
```
|
|
|
|
### Conflict Resolution
|
|
|
|
If a file is modified externally while editing:
|
|
|
|
1. **Error appears**: "Conflit: le fichier a été modifié sur le disque"
|
|
2. **Two options**:
|
|
- **Reload from disk**: Discard local changes, load external version
|
|
- **Overwrite**: Keep local changes, overwrite external version
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Issue: 400 Bad Request
|
|
|
|
**Symptom**: `GET /api/files/<path> 400 (Bad Request)`
|
|
|
|
**Cause**: Using old splat route format
|
|
|
|
**Fix**: Already fixed! The code now uses query params.
|
|
|
|
### Issue: Invalid Excalidraw Format
|
|
|
|
**Symptom**: "Invalid Excalidraw format" error
|
|
|
|
**Cause**: File uses wrong compression (zlib instead of LZ-String)
|
|
|
|
**Fix**: Already fixed! The parser now uses LZ-String.
|
|
|
|
### Issue: File Won't Open in Obsidian
|
|
|
|
**Symptom**: Obsidian shows error when opening file
|
|
|
|
**Cause**: File not in proper Obsidian format
|
|
|
|
**Fix**: Already fixed! Files are now saved with correct format.
|
|
|
|
## 📊 Verification Checklist
|
|
|
|
- [x] `lz-string` package installed
|
|
- [x] Backend routes use query params (`?path=`)
|
|
- [x] Backend uses LZ-String (not zlib)
|
|
- [x] Frontend services use query params
|
|
- [x] Files saved in Obsidian format
|
|
- [x] Front matter preserved
|
|
- [x] Unit tests pass (16/16)
|
|
- [x] Migration script available
|
|
- [x] Documentation complete
|
|
|
|
## 🎯 Next Steps
|
|
|
|
1. **Test with your vault**: Copy an Excalidraw file from Obsidian to the vault
|
|
2. **Verify round-trip**: Open → Edit → Save → Re-open in Obsidian
|
|
3. **Migrate old files**: Run migration script if needed
|
|
4. **Report issues**: Check console for any errors
|
|
|
|
## 📚 Additional Resources
|
|
|
|
- Full implementation details: `docs/EXCALIDRAW_IMPLEMENTATION.md`
|
|
- Backend utilities: `server/excalidraw-obsidian.mjs`
|
|
- Frontend service: `src/app/features/drawings/excalidraw-io.service.ts`
|
|
- Tests: `server/excalidraw-obsidian.test.mjs`
|
|
- Migration: `server/migrate-excalidraw.mjs`
|