From 769d3a31bbececdb5d54cf103410942852629e08 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 14 Nov 2025 02:57:07 +0000 Subject: [PATCH] feat: add Obsidian vault integration for modern Markdown notes Add comprehensive Obsidian integration as intermediate step toward PostgreSQL migration, enabling modern Markdown-based note editing: **Features:** - Obsidian Local REST API integration for vault access - Coordinate-based note matching (searches vault YAML frontmatter) - Shows top 5-8 closest matches when clicking burgs/markers - Modern Markdown editor with live preview - [[Wikilink]] support for connecting notes - "Open in Obsidian" button to jump to native app - Configuration UI for API setup and testing **Technical Implementation:** - modules/io/obsidian-bridge.js - Core API integration layer - modules/ui/obsidian-notes-editor.js - Markdown editor UI - modules/ui/obsidian-config.js - Configuration panel - OBSIDIAN_INTEGRATION.md - Complete setup/usage guide **Coordinate Matching:** - Parses YAML frontmatter for x/y coordinates - Calculates distance to clicked element - Supports nested (coordinates.x) and flat (x:) formats - Handles missing FMG IDs (common with PostgreSQL imports) **User Workflow:** 1. Configure Obsidian REST API connection 2. Click burg/marker in FMG 3. System finds matching notes by coordinates 4. Select note or create new one 5. Edit in modern Markdown editor 6. Save syncs to Obsidian vault instantly This replaces the "Win95-style TinyMCE" editor with a clean, modern Markdown experience while maintaining compatibility with the eventual PostgreSQL backend migration. Users can edit notes in either FMG or Obsidian - both stay in sync via file system. Version: 1.108.13 --- OBSIDIAN_INTEGRATION.md | 270 ++++++++++++++++++ index.html | 109 +++++++- modules/io/obsidian-bridge.js | 416 ++++++++++++++++++++++++++++ modules/ui/obsidian-config.js | 73 +++++ modules/ui/obsidian-notes-editor.js | 358 ++++++++++++++++++++++++ versioning.js | 2 +- 6 files changed, 1226 insertions(+), 2 deletions(-) create mode 100644 OBSIDIAN_INTEGRATION.md create mode 100644 modules/io/obsidian-bridge.js create mode 100644 modules/ui/obsidian-config.js create mode 100644 modules/ui/obsidian-notes-editor.js diff --git a/OBSIDIAN_INTEGRATION.md b/OBSIDIAN_INTEGRATION.md new file mode 100644 index 00000000..5389cd03 --- /dev/null +++ b/OBSIDIAN_INTEGRATION.md @@ -0,0 +1,270 @@ +# Obsidian Vault Integration for Fantasy Map Generator + +## Overview + +Fantasy Map Generator now supports deep integration with your Obsidian vault for managing map lore and notes! This allows you to: + +- Store all your world lore in Markdown format +- Edit notes in a modern Markdown editor (no more Win95-style TinyMCE!) +- Automatically link map elements to Obsidian notes by coordinates +- Keep your notes in sync between FMG and Obsidian +- Use [[wikilinks]] to connect related notes +- Edit in either FMG or Obsidian - changes sync both ways + +## Setup + +### 1. Install Obsidian Local REST API Plugin + +1. Open Obsidian +2. Go to **Settings** → **Community Plugins** +3. Click **Browse** and search for "Local REST API" +4. Install and **Enable** the plugin +5. Go to **Settings** → **Local REST API** +6. Copy your **API Key** (you'll need this!) +7. Note the **Server Port** (default: 27123) + +### 2. Configure in Fantasy Map Generator + +1. Open Fantasy Map Generator +2. Go to **Menu** → **Tools** → **⚙ Obsidian** +3. Enter your settings: + - **API URL**: `http://127.0.0.1:27123` (default) + - **API Key**: Paste from Obsidian plugin settings + - **Vault Name**: Name of your Obsidian vault +4. Click **Test Connection** to verify +5. Click **Save Configuration** + +## Usage + +### Linking Map Elements to Notes + +When you click on a **burg** or **marker** in FMG: + +1. FMG searches your Obsidian vault for notes with matching coordinates in YAML frontmatter +2. Shows you the top 5-8 closest matches +3. You select the note you want, or create a new one + +### Note Format + +Notes in your vault should have YAML frontmatter like this: + +```markdown +--- +fmg-id: burg123 +fmg-type: burg +coordinates: + x: 234.5 + y: 456.7 + lat: 45.23 + lon: -73.45 +tags: + - capital + - settlement + - ancient +aliases: + - Eldoria + - The Ancient City +--- + +# Eldoria + +The ancient capital sits upon the [[River Mystral]], founded in year 1203. + +## History + +The city was established by [[King Aldric the First]]... + +## Notable Locations + +- [[The Grand Library]] +- [[Temple of the Seven Stars]] +- [[Market Square]] +``` + +### Coordinate Matching + +Since your burgs/markers may have been imported from PostgreSQL without FMG IDs, the system matches by **X/Y coordinates**: + +- FMG extracts the coordinates from the clicked element +- Searches all `.md` files in your vault for matching `x:` and `y:` values +- Calculates distance and shows closest matches +- You pick the right one! + +### Supported Coordinate Formats + +The system recognizes these formats in YAML frontmatter: + +```yaml +# Nested object (recommended) +coordinates: + x: 123.4 + y: 567.8 + +# Or flat +x: 123.4 +y: 567.8 + +# Case insensitive +X: 123.4 +Y: 567.8 +``` + +### Creating New Notes + +If no matches are found: + +1. FMG offers to create a new note +2. Enter a name (e.g., "Eldoria") +3. Optionally specify a folder (e.g., "Locations/Cities") +4. FMG generates a template with coordinates +5. Opens in the Markdown editor +6. Saved directly to your Obsidian vault! + +### Editing Notes + +The modern Markdown editor includes: + +- **Live preview**: Toggle between edit/preview modes +- **[[Wikilinks]]**: Link to other notes in your vault +- **Syntax highlighting**: Clean monospace font +- **Open in Obsidian**: Button to jump to the note in Obsidian app +- **Save to Vault**: Changes sync immediately + +### Using Wikilinks + +Create connections between notes: + +```markdown +The [[King Aldric the First]] ruled from [[Eldoria]]. +The city controls access to [[River Mystral]]. +``` + +When you save in FMG, these links work in Obsidian! + +## Migration from PostgreSQL + +If you have existing lore in PostgreSQL with coordinates: + +1. Export your data to Markdown files with YAML frontmatter +2. Include `x`, `y`, `lat`, `lon` in the frontmatter +3. Place files in your Obsidian vault +4. FMG will auto-match by coordinates! + +Example export script template: + +```python +for location in locations: + frontmatter = f"""--- +fmg-type: {location.type} +coordinates: + x: {location.x} + y: {location.y} + lat: {location.lat} + lon: {location.lon} +tags: {location.tags} +--- + +# {location.name} + +{location.description} +""" + with open(f"vault/{location.name}.md", "w") as f: + f.write(frontmatter) +``` + +## Tips & Tricks + +### Organize Your Vault + +Create folders for different types: + +``` +My Vault/ +├── Locations/ +│ ├── Cities/ +│ ├── Landmarks/ +│ └── Regions/ +├── Characters/ +├── History/ +└── Lore/ +``` + +### Use Templates + +Create Obsidian templates for different element types: + +- `Templates/City.md` +- `Templates/Landmark.md` +- `Templates/Character.md` + +### Search and Graph + +In Obsidian: + +- Use **Search** (`Ctrl+Shift+F`) to find notes by coordinates +- Use **Graph View** to see connections between locations +- Use **Tags** to organize by type + +### Sync Across Devices + +Use Obsidian Sync or Git to keep your vault synced across computers! + +## Troubleshooting + +### Connection Failed + +- Make sure Obsidian is running +- Verify the Local REST API plugin is enabled +- Check the port number (default 27123) +- Try restarting Obsidian + +### No Matches Found + +- Check that your notes have `x:` and `y:` fields in frontmatter +- Verify coordinates are numbers, not strings +- Try increasing the search radius + +### Changes Not Appearing in Obsidian + +- Obsidian should auto-detect file changes +- If not, try switching to another note and back +- Or close/reopen the note + +## Advanced + +### Custom Coordinate Systems + +If you use a different coordinate system: + +1. Map your coordinates to FMG's system +2. Store both in frontmatter: +```yaml +coordinates: + x: 234.5 # FMG coordinates + y: 456.7 + custom_x: 1000 # Your system + custom_y: 2000 +``` + +### Database Bridge + +For the future PostgreSQL migration: + +1. Keep coordinates in both Obsidian and database +2. Use coordinates as the join key +3. Sync changes via API +4. Eventually replace file storage with DB + +## Future Features + +Planned enhancements: + +- [ ] Time slider - view notes across historical periods +- [ ] Automatic tagging by region/culture +- [ ] Bulk import from database +- [ ] Real-time collaboration +- [ ] Custom Markdown extensions + +--- + +**Enjoy your modern, Markdown-powered world-building! 🗺️✨** diff --git a/index.html b/index.html index 9175879e..b644322f 100644 --- a/index.html +++ b/index.html @@ -2062,6 +2062,9 @@ Namesbase + @@ -4963,6 +4966,107 @@ + + + + + +