From 3f966741052553a4567a4363f4d2878eade9a31f Mon Sep 17 00:00:00 2001 From: Jennie Robinson Faber Date: Mon, 2 Mar 2026 09:53:37 +0000 Subject: [PATCH] Update nginx configuration for homepage meta tags and CSS injection; add workspace.json changes for article tabs and release notes; update .gitignore to exclude README.md and workspace.json. --- .gitignore | 2 + content/articles/.obsidian/workspace.json | 85 ++- docs/OBSIDIAN_SETUP_GUIDE.md | 523 ------------------- docs/README.md | 344 ------------ docs/TECHNICAL_ARCHITECTURE.md | 607 ---------------------- docs/TROUBLESHOOTING.md | 564 -------------------- nginx.conf | 24 + 7 files changed, 99 insertions(+), 2050 deletions(-) delete mode 100644 docs/OBSIDIAN_SETUP_GUIDE.md delete mode 100644 docs/README.md delete mode 100644 docs/TECHNICAL_ARCHITECTURE.md delete mode 100644 docs/TROUBLESHOOTING.md diff --git a/.gitignore b/.gitignore index 75904a9..e204627 100644 --- a/.gitignore +++ b/.gitignore @@ -31,3 +31,5 @@ conflict-files-obsidian-git.md # Project docs (local only) /docs /migration +docs/README.md +content/articles/.obsidian/workspace.json diff --git a/content/articles/.obsidian/workspace.json b/content/articles/.obsidian/workspace.json index ccf7966..4732269 100644 --- a/content/articles/.obsidian/workspace.json +++ b/content/articles/.obsidian/workspace.json @@ -4,24 +4,85 @@ "type": "split", "children": [ { - "id": "77a37c5d6b29181c", + "id": "0fb2a4ae0aa9ed09", "type": "tabs", "children": [ { - "id": "53add52357bc7f3f", + "id": "f1152658e00fd90b", "type": "leaf", "state": { - "type": "split-diff-view", + "type": "markdown", "state": { - "aFile": "content/articles/.obsidian/workspace.json", - "bFile": "content/articles/.obsidian/workspace.json", - "aRef": "" + "file": "co-op-structure.md", + "mode": "preview", + "source": false }, - "icon": "diff", - "title": "Diff: workspace.json" + "icon": "lucide-file", + "title": "co-op-structure" + } + }, + { + "id": "e817c7ccfbb69b99", + "type": "leaf", + "state": { + "type": "release-notes", + "state": { + "currentVersion": "1.11.1" + }, + "icon": "lucide-book-up", + "title": "Release Notes 1.11.1" + } + }, + { + "id": "199af8298e590a22", + "type": "leaf", + "state": { + "type": "release-notes", + "state": { + "currentVersion": "1.11.2" + }, + "icon": "lucide-book-up", + "title": "Release Notes 1.11.2" + } + }, + { + "id": "d41a728647cc5df7", + "type": "leaf", + "state": { + "type": "release-notes", + "state": { + "currentVersion": "1.11.3" + }, + "icon": "lucide-book-up", + "title": "Release Notes 1.11.3" + } + }, + { + "id": "11cfd8ac224cab6e", + "type": "leaf", + "state": { + "type": "release-notes", + "state": { + "currentVersion": "1.11.4" + }, + "icon": "lucide-book-up", + "title": "Release Notes 1.11.4" + } + }, + { + "id": "f34077a8821f1aa2", + "type": "leaf", + "state": { + "type": "release-notes", + "state": { + "currentVersion": "1.11.5" + }, + "icon": "lucide-book-up", + "title": "Release Notes 1.11.5" } } - ] + ], + "currentTab": 5 } ], "direction": "vertical" @@ -193,8 +254,10 @@ "obsidian-git:Open Git source control": false } }, - "active": "53add52357bc7f3f", + "active": "f34077a8821f1aa2", "lastOpenFiles": [ + "impact-measurement.md", + "market-analysis.md", "decisions-and-conflict.md", "publisher-contract-review.md", "actionable-steam-metrics.md", @@ -220,8 +283,6 @@ "results-flow.md", "process-development.md", "pitching-to-publishers.md", - "market-analysis.md", - "impact-measurement.md", "game-discovery-toolkit.md", "financial-modelling.md", "expo-tips.md", diff --git a/docs/OBSIDIAN_SETUP_GUIDE.md b/docs/OBSIDIAN_SETUP_GUIDE.md deleted file mode 100644 index 9391a71..0000000 --- a/docs/OBSIDIAN_SETUP_GUIDE.md +++ /dev/null @@ -1,523 +0,0 @@ -# Obsidian Vault Setup Guide - -**For:** Wiki-GhostGuild Content Contributors - -This guide helps you set up and work with the wiki-ghostguild content folder as an Obsidian vault. - ---- - -## Quick Start (5 minutes) - -### 1. Clone the Repository - -```bash -git clone https://git.ghostguild.org/org/wiki-ghostguild.git -cd wiki-ghostguild -npm install -``` - -### 2. Open Obsidian - -- Open Obsidian -- Click "Open folder as vault" -- Navigate to: `/path/to/wiki-ghostguild/content/articles/` -- Click "Open" - -### 3. Install Required Plugins - -The vault has plugin configurations ready, but you need to **manually install the plugins first**: - -**Step 1: Enable Community Plugins** -1. Go to **Settings → Community plugins** -2. Click "Turn off restricted mode" (if you see this) -3. Click "Browse" to open plugin browser - -**Step 2: Install Obsidian Git** -1. Search for **"Obsidian Git"** by Vinzent03 -2. Click "Install" -3. Click "Enable" -4. ⚠️ Important: Restart Obsidian or reload the vault - -**Step 3 (Optional): Install Linter & Templater** -1. Search for **"Linter"** by plexus -2. Install & enable -3. Search for **"Templater"** by SilentVoid -4. Install & enable - -### 4. You're Ready! - -The vault is now configured and ready to use. Wikilinks, images, and Git integration are all set up. - ---- - -## Understanding the Setup - -### What's Configured - -| Feature | Setting | Value | -|---------|---------|-------| -| **Attachment Folder** | Saves images to | `/public/img/` | -| **Wikilinks** | Enabled for | `[[Page Title]]` syntax | -| **Auto-linking** | When renaming | Updates links automatically | -| **Git Integration** | Via plugin | Obsidian Git (auto-pull on startup) | - -### How It Works - -1. **You write** in Obsidian using wikilinks: `[[Page Title]]` -2. **You paste images** which auto-save to `/public/img/` -3. **You commit** via Obsidian Git: `Mod+Shift+G` (or menu) -4. **Build transforms**: Wikilinks → `/articles/page-title`, images → `/img/filename` -5. **Readers see** proper links and images in browser - ---- - -## Creating & Editing Articles - -### Creating a New Article - -**Option A: In Obsidian** - -1. Create new file: `Cmd+N` (Mac) or `Ctrl+N` (Windows) -2. Use Templater plugin if available (shortcut: `Mod+T`) -3. Add frontmatter (see template below) -4. Write content using wikilinks freely - -**Option B: Use Template** - -Start with this frontmatter: - -```yaml ---- -title: "Article Title Here" -description: "Brief description for preview/SEO" -category: "strategy" # or: funding, operations, programs, templates, studio-development, accessibility -tags: - - baby-ghosts - - p1 # or p0, p2 -accessLevel: "member" # or: public, cohort, admin -author: "Author Name" -publishedAt: '2025-11-10T11:13:26.520Z' ---- - -# Article Title Here - -Write your content below... -``` - -### Key Frontmatter Fields - -| Field | Required | Options | Example | -|-------|----------|---------|---------| -| `title` | ✅ | Any string | `"Accessibility Guide: Disability"` | -| `description` | ⭕ | Any string | `"Guide for studios..."` | -| `category` | ⭕ | See list below | `"accessibility"` | -| `tags` | ⭕ | Array of strings | `["baby-ghosts", "p1"]` | -| `accessLevel` | ⭕ | `public`, `member`, `cohort`, `admin` | `"member"` | -| `author` | ⭕ | Name string | `"Baby Ghosts"` | -| `publishedAt` | ⭕ | ISO date | `'2025-11-10T13:00:00Z'` | - -**Categories:** -- `strategy` - Strategic planning -- `funding` - Financing & grants -- `operations` - Day-to-day operations -- `programs` - Program descriptions -- `templates` - Reusable templates -- `studio-development` - Studio building -- `accessibility` - Accessibility guides - ---- - -## Writing Content - -### Linking to Other Articles - -**Use wikilinks - they're cleaner in Obsidian:** - -```markdown -See the [[Communication Norms Document for Game Studios]] -Or [[P1 - Publishing & Marketing Playbook for Game Studios|shortcut text]] -``` - -Obsidian shows these as links. At build time, they transform to proper `/articles/slug` links. - -**Why this works:** -- ✅ Wikilinks work in Obsidian's graph view and backlinks -- ✅ You get autocomplete when typing `[[` -- ✅ Renaming articles updates all links automatically -- ✅ Build transforms them to standard markdown for the web - -### Adding Images - -**Simply paste into Obsidian:** - -1. Copy image (or screenshot) -2. Place cursor in article -3. Paste: `Cmd+V` (Mac) or `Ctrl+V` (Windows) -4. Obsidian prompts for filename -5. Image saves to `/public/img/` automatically - -**Use descriptive filenames:** -- ✅ Good: `meeting-workflow-diagram.png` -- ❌ Bad: `image1.png`, `Screen Shot 2025-11-10.png` - -**Wikilink syntax:** -```markdown -![[meeting-workflow-diagram.png]] -``` - -Or with alt text: -```markdown -![[meeting-workflow-diagram.png|Workflow for facilitating meetings]] -``` - -### Code Blocks - -Standard markdown fenced code blocks work great: - -````markdown -```python -def hello_world(): - print("Hello, GhostGuild!") -``` -```` - -### Tables - -```markdown -| Feature | Benefit | -|---------|---------| -| Flexibility | Adapt to your needs | -| Accessibility | Include everyone | -``` - ---- - -## Using Git for Collaboration - -### Daily Workflow - -``` -Morning: -1. Open Obsidian - - Auto-pulls latest changes - - Shows sync notifications -2. Start editing - -During work: -3. Edit articles -4. Add/paste images -5. Preview in Obsidian - -Before finishing: -6. Commit changes via Obsidian Git - - Mod+Shift+G → "Commit and Push" - - Or use menu: Obsidian Git → Commit -7. Enter commit message (see examples below) -8. Push to Forgejo - -Evening: -9. Optional: Verify changes live on staging/production -``` - -### Good Commit Messages - -**Format:** -``` -: - -Optional longer explanation... -``` - -**Types:** -- `content:` - Article edits -- `new:` - New article -- `images:` - Image additions -- `fix:` - Bug fixes in content -- `meta:` - Frontmatter changes - -**Examples:** -``` -content: Expand accessibility guide with mental health section - -Added section on creating a safe environment for people with anxiety -and depression, including practical accommodations. - ---- - -new: Add case study for Studio XYZ - -Documents their transition from traditional to cooperative structure -over 18 months, with lessons learned. - ---- - -images: Add diagrams to conflict resolution guide - -Created flowchart for escalation process and decision tree for -choosing resolution approach. -``` - -### Handling Conflicts - -**If you see a conflict:** - -1. Open Obsidian -2. Look for `conflict-files-obsidian-git.md` file -3. Find the article with conflict markers: - ```markdown - <<<<<<< HEAD - Your version - ======= - Their version - >>>>>>> main - ``` -4. Choose correct version (or merge manually) -5. Remove conflict markers -6. Save -7. Commit: `Conflict resolved: merged changes in article-name.md` - -**Prevent conflicts:** -- Pull before starting work -- Work on different articles when possible -- Push frequently (every 30-60 min) -- Communicate about big edits - ---- - -## Keyboard Shortcuts (Recommended) - -**Set up in Obsidian Settings → Hotkeys:** - -| Action | Mac | Windows | -|--------|-----|---------| -| New file | `Cmd+N` | `Ctrl+N` | -| Quick switcher | `Cmd+O` | `Ctrl+O` | -| Commit & Push | `Mod+Shift+G` | `Mod+Shift+G` | -| Open command palette | `Cmd+P` | `Ctrl+P` | - -(These are configured in `.obsidian/hotkeys.json`) - ---- - -## Obsidian Plugins - -### Required Plugins (Must Install) - -1. **Obsidian Git** - Commit/push directly from Obsidian - - **Status:** Configured but requires manual installation - - **To install:** See "Quick Start → Step 3" above - - **Features:** - - Auto-pulls on startup - - Auto-backup option (disabled to prevent constant commits) - - Settings → Obsidian Git - - **Shortcut:** `Mod+Shift+G` to commit & push - -### Optional Plugins (Recommended) - -2. **Linter** - Keep markdown formatting consistent - - Helps maintain clean, consistent formatting - - Settings → Linter - - Auto-fixes formatting on save - -3. **Templater** - Create article templates - - Create templates for different article types - - Settings → Templater - - Useful if you create many articles of the same type - -### Installing Additional Plugins - -1. Go to **Settings → Community plugins** -2. Click **"Browse"** to browse community plugins -3. Search for plugin name -4. Click **"Install"** → **"Enable"** -5. Configure settings if needed - ---- - -## Common Issues - -### "I don't see the Obsidian Git plugin" - -**Problem:** After opening the vault, the Git plugin isn't visible or available - -**Root cause:** Plugins are configured in the vault, but need to be manually installed from the Obsidian community plugins browser first. - -**Solution:** -1. Go to **Settings → Community plugins** -2. If you see "Turn off restricted mode" - click it first -3. Click **"Browse"** button -4. Search for **"Obsidian Git"** by Vinzent03 -5. Click **"Install"** -6. Click **"Enable"** -7. **Restart Obsidian** or reload the vault -8. Check `Obsidian Git` menu → should now show Git options -9. Try commit shortcut: **`Mod+Shift+G`** - -**Still not working?** -- Make sure you're not in "Restricted mode" -- Check if Internet connection is working (needed to browse plugins) -- Try restarting Obsidian completely -- See Troubleshooting.md for more help - ---- - -### "Can't find vault" - -**Problem:** Obsidian can't open the `/content/articles/` folder - -**Solution:** -```bash -# Make sure you're in the right directory -cd /path/to/wiki-ghostguild -ls content/articles/ - -# Then open Obsidian and use full path: -# Mac: /Users/yourname/Sites/wiki-ghostguild/content/articles/ -# Windows: C:\Users\yourname\Sites\wiki-ghostguild\content\articles\ -``` - -### Images not saving - -**Problem:** Pasting image doesn't auto-save to `/public/img/` - -**Solution:** -1. Check Settings → Files & Links -2. Verify "Attachment folder path": `../../public/img` -3. Make sure folder exists: `ls public/img/` -4. Try again: Paste image with Cmd+V - -### Wikilinks not working - -**Problem:** `[[Page Name]]` shows as red/broken - -**Solutions:** -1. **Check spelling** - Links are exact-match -2. **Check frontmatter title** - Link uses article title, not filename -3. **Restart Obsidian** - Sometimes cache issues -4. **Check graph view** - Obsidian → Tab → Graph to see all pages - -### Git conflicts - -**Problem:** Can't push because of merge conflict - -**Solutions:** -1. Pull first: Obsidian Git → Pull -2. Resolve conflicts (see "Handling Conflicts" above) -3. Commit the resolution -4. Push - -### "Port already in use" - -**Problem:** `npm run dev` fails with port error - -**Solution:** -```bash -# Find and kill the existing dev server -ps aux | grep nuxt -kill -9 - -# Then try again -npm run dev -``` - ---- - -## Preview & Testing - -### Preview in Obsidian - -1. Open any article -2. Toggle preview mode: `Cmd+E` (Mac) or `Ctrl+E` (Windows) -3. See how content looks (but wikilinks won't work - they're transformed at build) - -### Test in Browser - -```bash -# Start dev server -npm run dev - -# Visit: http://localhost:3000/articles/article-slug - -# Check that: -# - All wikilinks rendered as clickable links -# - Images display correctly -# - Frontmatter title shows -# - Formatting looks right -``` - -### Test Before Pushing - -```bash -# Run static build -npm run generate - -# Preview output -npm run preview - -# Visit: http://localhost:3000/articles/article-slug -# This is what production looks like -``` - ---- - -## File Structure - -What you need to know: - -``` -wiki-ghostguild/ -├── content/articles/ ← You edit files HERE -│ ├── article-one.md -│ ├── article-two.md -│ └── .obsidian/ ← Vault configuration (shared) -├── public/img/ ← Images go HERE (via Obsidian paste) -├── app/ ← Website code (don't edit) -├── app/server/ -│ └── plugins/ -│ └── wikilink-transform.ts ← Transforms wikilinks & images -└── docs/ ← Documentation -``` - ---- - -## Advanced: How Transformation Works - -**You don't need to understand this, but here's what happens:** - -1. **You write in Obsidian:** - ```markdown - [[P0 - Communication Norms]] - ![[diagram.jpg]] - ``` - -2. **At build time, the Nitro plugin transforms to:** - ```markdown - [Communication Norms](/articles/communication-norms-document-for-game-studios) - ![diagram.jpg](/img/diagram.jpg) - ``` - -3. **Readers see proper links:** - - Clicking link → goes to `/articles/communication-norms-document-for-game-studios` - - Image loads from `/img/diagram.jpg` (in /public/) - -**Why this approach:** -- ✅ Wikilinks work perfectly in Obsidian -- ✅ Automatic link updates when renaming -- ✅ No runtime overhead (transform at build) -- ✅ Clean web links for readers - ---- - -## Questions? - -Check: -1. **Obsidian Help**: https://help.obsidian.md -2. **Obsidian Git Plugin**: https://github.com/Vinzent03/obsidian-git -3. **Technical Docs**: See `docs/TECHNICAL_ARCHITECTURE.md` -4. **Troubleshooting**: See `docs/TROUBLESHOOTING.md` - -Or ask your team! - ---- - -**Remember:** The vault is designed to be simple and collaborative. Both users can edit freely, Git handles versioning, and the build transforms everything for the web. Happy writing! diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index ea25ad2..0000000 --- a/docs/README.md +++ /dev/null @@ -1,344 +0,0 @@ -# Wiki-GhostGuild Documentation - -Welcome to the documentation for the wiki-ghostguild content system. - ---- - -## Quick Links - -**Starting out?** → Read [`OBSIDIAN_SETUP_GUIDE.md`](./OBSIDIAN_SETUP_GUIDE.md) - -**Having problems?** → Check [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md) - -**Want technical details?** → See [`TECHNICAL_ARCHITECTURE.md`](./TECHNICAL_ARCHITECTURE.md) - ---- - -## Documentation Structure - -### [OBSIDIAN_SETUP_GUIDE.md](./OBSIDIAN_SETUP_GUIDE.md) - -**For:** All content contributors - -Everything you need to know about: -- Opening the Obsidian vault -- Writing articles with wikilinks -- Adding images -- Using Git for collaboration -- Common workflows -- Keyboard shortcuts - -**Start here if:** You're new to the system or new to the team - ---- - -### [TECHNICAL_ARCHITECTURE.md](./TECHNICAL_ARCHITECTURE.md) - -**For:** Technical team members, maintainers - -Deep dive into: -- How the system works (Obsidian → Nuxt → Web) -- Wikilink transformation plugin -- Content processing pipeline -- Image handling -- Build process -- Performance characteristics -- Edge cases and future enhancements - -**Read this if:** You want to understand how everything works, or you're maintaining the codebase - ---- - -### [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - -**For:** Anyone encountering issues - -Practical solutions for: -- Obsidian issues (vault, wikilinks, images, Git) -- Git issues (push, conflicts) -- Build problems -- Deployment issues -- Network issues -- Article problems - -**Use this if:** Something isn't working and you need to fix it - ---- - -## System Overview - -``` -You write in Obsidian Build transforms Web readers see - ↓ ↓ ↓ - -[[Page Title]] → Wikilink Transform → [Title](/articles/slug) -![[image.jpg]] → Image Transform → ![](/img/image.jpg) - -(with Git for collaboration) -``` - ---- - -## Getting Started (5 minutes) - -1. **Clone the repo** - ```bash - git clone https://your-forgejo.com/org/wiki-ghostguild.git - cd wiki-ghostguild - npm install - ``` - -2. **Open Obsidian** - - Open vault: `content/articles/` - - Settings auto-load - - Plugins auto-enable - -3. **Start editing** - - Open an article - - Make a change - - Git commit via Obsidian Git - - Push - -4. **Test locally** - ```bash - npm run dev - # Visit http://localhost:3000 - ``` - ---- - -## Key Concepts - -### Wikilinks - -Obsidian native linking syntax: -```markdown -[[Page Title]] -[[Long Name|Short Text]] -``` - -**At build:** Transforms to `/articles/slug` format for web - -**Why:** Clean in Obsidian, proper links on web - ---- - -### Images - -Paste images directly in Obsidian: -```markdown -![[diagram.jpg]] -``` - -**Saving:** Auto-saves to `/public/img/` - -**At build:** Transforms to `/img/filename` format - ---- - -### Collaboration - -Both users edit via Obsidian, commit via Git: -1. User A edits → commits → pushes -2. User B pulls → gets User A's changes -3. User B edits → commits → pushes -4. Git handles versioning and conflicts - ---- - -### Frontmatter - -Every article starts with metadata: - -```yaml ---- -title: "Article Title" -description: "Brief description" -category: "accessibility" # or strategy, funding, etc. -tags: [baby-ghosts, p0] -accessLevel: "member" # or public, cohort, admin -author: "Author Name" -publishedAt: '2025-11-10T13:00:00Z' ---- -``` - -**Required:** `title` - -**Optional:** Everything else (but frontmatter itself is required) - ---- - -## Common Workflows - -### Adding a New Article - -1. In Obsidian: `Cmd+N` (new file) -2. Add frontmatter (copy from template or example) -3. Write content using wikilinks -4. Add images (paste with `Cmd+V`) -5. Git: Commit & push -6. Test: `npm run generate` then `npm run preview` - -### Updating Existing Article - -1. Open article in Obsidian -2. Edit content -3. Update wikilinks if needed -4. Commit with descriptive message -5. Push - -### Fixing a Typo - -1. Find typo in article -2. Edit -3. Commit: `fix: correct typo in article-name` -4. Push - -### Handling a Conflict - -1. Pull (Obsidian Git) -2. Look for conflict markers in file -3. Choose correct version -4. Remove markers -5. Save -6. Commit: `Resolve conflict` -7. Push - ---- - -## File Structure - -``` -wiki-ghostguild/ -├── docs/ ← You are here -│ ├── README.md ← Start here -│ ├── OBSIDIAN_SETUP_GUIDE.md ← User guide -│ ├── TECHNICAL_ARCHITECTURE.md ← How it works -│ └── TROUBLESHOOTING.md ← Problem solving -├── content/ -│ └── articles/ ← Your content (Obsidian vault) -│ ├── article-one.md -│ ├── article-two.md -│ └── .obsidian/ ← Vault configuration -├── public/ -│ └── img/ ← Images (auto-saved by Obsidian) -├── app/ -│ └── server/ -│ └── plugins/ -│ └── wikilink-transform.ts ← Transformation magic -└── package.json -``` - ---- - -## Quick Reference - -### Commands - -```bash -npm run dev # Start dev server (port 3000, hot reload) -npm run generate # Build static site to .output/ -npm run preview # Preview built site -npm run build # Build application (if deploying) - -git pull # Get latest changes -git add -A # Stage changes -git commit -m "msg" # Commit -git push # Push to Forgejo -``` - -### Keyboard Shortcuts (Obsidian) - -- `Cmd+N` - New file -- `Cmd+O` - Quick switcher (search articles) -- `Cmd+P` - Command palette -- `Cmd+E` - Toggle preview -- `Mod+Shift+G` - Commit & push (via Obsidian Git) - ---- - -## Support - -### Finding Help - -1. **Check this documentation** - Most answers are here -2. **Search online** - Error message + "Obsidian" or "Nuxt" -3. **Ask your team** - Slack, email, or in person - -### Reporting Issues - -If you find a bug or have a feature request: - -1. **Document it** - What happened? What did you expect? -2. **Check if known** - Look in TROUBLESHOOTING.md -3. **Create issue** - In Forgejo/GitHub -4. **Include context** - OS, error message, steps to reproduce - ---- - -## Maintenance - -### Regular Tasks - -**Weekly:** -- Run `npm run generate` to check build works -- Review commit messages - -**Monthly:** -- Test full workflow -- Check article links (broken link audit) - -**Quarterly:** -- Update dependencies (`npm outdated`, `npm update`) -- Review Obsidian plugin updates - ---- - -## FAQ - -**Q: Do I need to understand how the transformation works?** - -A: No! Just know that: -- Wikilinks work in Obsidian -- They transform to normal links on the web -- Same for images - -**Q: Can two people edit at the same time?** - -A: Yes! As long as they edit different articles. If you edit the same article, Git will flag a conflict (easy to resolve). - -**Q: What if I make a typo and push by accident?** - -A: Just fix it and push again. Git tracks history, so you can revert if needed. - -**Q: How do I know my changes are live?** - -A: After pushing, the server automatically rebuilds and deploys (depends on your CI/CD setup). - -**Q: Can I use Obsidian plugins?** - -A: Yes! Go to Settings → Community plugins → Browse. Just avoid plugins that modify file structure. - ---- - -## Next Steps - -- **New contributor?** Read [OBSIDIAN_SETUP_GUIDE.md](./OBSIDIAN_SETUP_GUIDE.md) -- **Having issues?** Check [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) -- **Want to learn more?** Read [TECHNICAL_ARCHITECTURE.md](./TECHNICAL_ARCHITECTURE.md) - ---- - -## Feedback - -Found something unclear? Have a suggestion? - -- Comment in a GitHub/Forgejo issue -- Edit the docs (improve them!) -- Ask on the team channel - ---- - -**Last Updated:** November 2025 - -**Maintained by:** Wiki-GhostGuild Team diff --git a/docs/TECHNICAL_ARCHITECTURE.md b/docs/TECHNICAL_ARCHITECTURE.md deleted file mode 100644 index c3869d8..0000000 --- a/docs/TECHNICAL_ARCHITECTURE.md +++ /dev/null @@ -1,607 +0,0 @@ -# Technical Architecture: Obsidian-Nuxt Integration - -**For:** Technical team members, maintainers - ---- - -## System Overview - -``` -Obsidian Vault (source) Nuxt Content (processing) Web (output) - ↓ ↓ ↓ -content/articles/*.md → Wikilink Transform Plugin → /articles/slug - with [[links]] (Nitro server plugin) with /articles/ links - with ![[images]] with /img/ references - Image embed transformation - (Nitro server plugin) - - ↓ - - Nuxt build generates - Static HTML + JSON -``` - ---- - -## Architecture Components - -### 1. Obsidian Vault Configuration - -**Location:** `/content/articles/.obsidian/` - -**Key Files:** -- `app.json` - Settings (attachment folder, link format, etc.) -- `community-plugins.json` - List of plugins to enable -- `hotkeys.json` - Keyboard shortcuts -- `plugins/obsidian-git/data.json` - Git plugin configuration - -**Attachment Folder:** -```json -{ - "attachmentFolderPath": "../../public/img" -} -``` - -This tells Obsidian to save images to `/public/img/` instead of keeping them in the vault. - -**User-Specific (Gitignored):** -- `workspace.json` - Open files, window layout (per-user) -- `appearance.json` - Theme preferences (per-user) -- `cache/` - Obsidian's internal cache -- `graph.json` - Graph view state - -**Shared (Committed):** -- `app.json` - Core settings -- `community-plugins.json` - Plugin list -- `hotkeys.json` - Team shortcuts - ---- - -### 2. Wikilink Transformation Plugin - -**Location:** `/app/server/plugins/wikilink-transform.ts` - -**Hook:** `content:file:beforeParse` - -**Timing:** Runs during Nuxt Content processing, before markdown parsing - -**Transformations:** - -#### Wikilinks → Markdown Links - -```typescript -// Input -[[P0 - Communication Norms for Game Studios]] -[[Grant Writing Guide|Grant Guide]] - -// Output -[Communication Norms for Game Studios](/articles/communication-norms-for-game-studios) -[Grant Guide](/articles/grant-writing-guide) - -// Logic -1. Strip P0/P1/P2 prefix -2. Convert title to slug (lowercase, spaces→hyphens, special chars→removed) -3. Create markdown link with /articles/ prefix -``` - -**Slug Generation:** -```typescript -function titleToSlug(title: string): string { - return title - .toLowerCase() - .replace(/['"]/g, '') // Remove quotes - .replace(/&/g, 'and') // & → and - .replace(/[^a-z0-9\s-]/g, '') // Remove special chars - .replace(/\s+/g, '-') // Spaces → hyphens - .replace(/-+/g, '-') // Collapse hyphens - .replace(/^-|-$/g, ''); // Trim edges -} - -// Examples: -"Grant Writing & Funding Strategy" → "grant-writing-and-funding-strategy" -"Co-op: Structure & Governance" → "co-op-structure-and-governance" -"Q&A: Funding" → "qa-funding" -``` - -#### Image Embeds → Markdown Images - -```typescript -// Input -![[diagram.jpg]] -![[workflow.png|Team workflow diagram]] - -// Output -![diagram.jpg](/img/diagram.jpg) -![Team workflow diagram](/img/workflow.png) - -// Logic -1. Extract filename and optional alt text -2. Create markdown image with /img/ prefix -``` - ---- - -### 3. Content Processing Pipeline - -**Sequence:** - -``` -1. File read from disk - File: /content/articles/article-name.md - - ↓ - -2. content:file:beforeParse hook (OUR PLUGIN) - - Extract wikilinks: [[...]] - - Extract image embeds: ![[...]] - - Transform both to markdown syntax - - Update file.body - - ↓ - -3. Frontmatter parsing (gray-matter) - - Extract YAML frontmatter - - Validate against schema - - ↓ - -4. Markdown parsing (Nuxt Content) - - Convert markdown to AST - - Generate HTML structure - - ↓ - -5. Static generation - - Render article pages - - Create JSON payloads - - Output to .output/ -``` - -**No Markdown Plugins Needed:** - -Nuxt Content v3 uses Nuxt's built-in markdown processor. We don't need remark/rehype plugins because the Nitro plugin hook runs before all parsing. - ---- - -### 4. Image Handling - -**Storage:** `/public/img/` - -**Workflow:** - -``` -User in Obsidian - ↓ -Pastes image (Cmd+V) - ↓ -Obsidian saves to /public/img/ - ↓ -User writes ![[filename.jpg]] - ↓ -Git add + commit - ↓ -Image goes to repository - ↓ -At build: - - Plugin transforms ![[filename.jpg]] → ![...](/img/filename.jpg) - - Build copies /public/img/ to output - ↓ -Web server serves /img/filename.jpg -``` - -**Path Resolution:** - -When Obsidian saves image from vault at `/content/articles/`: -``` -From: /content/articles/some-article.md -To: /public/img/ -Relative: ../../public/img - -So when you paste in Obsidian, it: - Saves to: /public/img/ - Creates: ![image](../../public/img/image.jpg) -``` - -The transformation plugin converts this to `/img/image.jpg` for web output. - ---- - -### 5. Nuxt Content Collection - -**Configuration:** `content.config.ts` - -```typescript -export default defineContentConfig({ - collections: { - articles: defineCollection({ - type: "data", - source: "**/*.md", // Finds all .md files - schema: z.object({ - title: z.string(), - description: z.string().optional(), - category: z.string().optional(), - tags: z.array(z.string()).optional(), - author: z.string().optional(), - contributors: z.array(z.string()).optional(), - published: z.boolean().default(true), - featured: z.boolean().default(false), - accessLevel: z.string().optional(), - publishedAt: z.string().optional(), - }), - }), - }, -}); -``` - -**Validation:** -- Frontmatter must match schema -- Missing required fields cause build errors -- All fields run through Zod validation - ---- - -### 6. Git Workflow Integration - -**Via Obsidian Git Plugin** - -**Configuration:** `.obsidian/plugins/obsidian-git/data.json` - -```json -{ - "autoPullOnBoot": true, // Pull on startup - "autoPullInterval": 5, // Pull every 5 minutes - "disablePush": false, // Allow pushing - "pullBeforePush": true, // Always pull before pushing - "conflictHandlingStrategy": "ask" // Ask on conflicts -} -``` - -**User Workflow:** - -1. **User A** edits article, commits, pushes -2. **User B** starts Obsidian → auto-pulls User A's changes -3. **User B** edits different article → no conflict -4. **User B** commits & pushes -5. **User A** continues working → might pull when prompted - -**Conflict Resolution:** - -If both users edit same file: -``` -1. Pull fails with conflict -2. Obsidian Git creates conflict-files-obsidian-git.md -3. User sees conflict markers in file: - <<<<<<< HEAD - User A's version - ======= - User B's version - >>>>>>> main -4. User manually resolves (chooses/merges versions) -5. User commits resolution -6. User pushes -``` - ---- - -## Build Process - -### Development (`npm run dev`) - -```bash -# Starts: -# 1. Nuxt dev server (hot reload) -# 2. Watches /content/articles/ for changes -# 3. When file saves: re-processes & hot-reload in browser - -npm run dev -# → http://localhost:3000 -# → Changes live-update without refresh -``` - -### Production (`npm run generate`) - -```bash -# Builds static site: -# 1. Processes all content files -# 2. Runs wikilink transformation -# 3. Generates HTML pages + JSON -# 4. Optimizes assets -# 5. Outputs to .output/public/ - -npm run generate -# → .output/public/ contains complete static site -# → Ready to deploy to CDN/hosting -``` - -### Static Preview (`npm run preview`) - -```bash -# Starts server serving built output: -# Shows what production will look like - -npm run preview -# → http://localhost:3000 -# → Serves from .output/public/ -``` - ---- - -## File Mappings - -**Article Files → URL Slugs:** - -``` -Obsidian filename Content title URL slug -──────────────────────────────────────────────────────────────────────── -communication-norms*.md Communication Norms Document /articles/communication-norms-document-for-game-studios -meeting-agenda*.md Meeting Agenda & Facilitation /articles/meeting-agenda-facilitation-guide-for-game-studios -co-op-structure*.md Co-op: Structure & Governance /articles/co-op-structure-and-governance - -*Actual filename doesn't matter for slug generation -Slug comes from frontmatter title -``` - -**Why this matters:** - -If you rename a file in Obsidian: -- ❌ Obsidian updates internal links automatically (good!) -- ✅ Slug stays same (derived from title, not filename) -- If you change the title in frontmatter: slug changes → URL changes - ---- - -## Performance Characteristics - -### Build Times - -| Operation | Time | Notes | -|-----------|------|-------| -| Dev server startup | ~10-15s | Nuxt init + content processing | -| Hot reload | ~1-2s | Single file change | -| Full static build | ~30-60s | 42 articles + optimization | -| Content indexing | ~100ms | Build-time caching | - -### Runtime Performance - -- **No runtime transformation** - All done at build -- **Static HTML output** - Zero processing at serve time -- **Fast first page load** - No client-side rendering for content - -### Scaling - -- **100 articles** - Build still <60s -- **1000 articles** - Might need optimization (parallel builds) -- **Image count** - No impact (images in /public/, not in content) - ---- - -## Edge Cases & Solutions - -### Case Sensitivity - -**Problem:** Filenames case-sensitive on Linux, case-insensitive on Mac - -**Solution:** Always use lowercase slugs -```yaml -# ✅ Good -- [[Grant Writing Guide]] -- [[case-study-studio-xyz]] - -# ❌ Problematic -- [[Grant WRITING Guide]] -- [[Case-Study-Studio-XYZ]] -``` - -### Special Characters - -**In Article Titles:** -``` -Input: "Co-op: Structure & Governance" -Slug: "co-op-structure-and-governance" - -Input: "Q&A: Funding" -Slug: "qa-funding" - -Input: "The "Beginning"" -Slug: "the-beginning" -``` - -**In Image Names:** -``` -✅ Good: meeting-workflow-diagram.jpg -❌ Bad: Meeting Workflow Diagram.jpg (spaces) -❌ Bad: image (2).jpg (parentheses) -``` - -### Circular References - -**Not a problem:** -- Article A links to Article B -- Article B links to Article A -- Both work fine (static links, no runtime resolution) - -### Non-Existent Links - -**Behavior:** -- Wikilink transforms to `/articles/non-existent-page` -- User clicks → sees 404 page -- No build error - -**Detection (optional enhancement):** -```typescript -// Could validate at build time: -// - Get all article slugs -// - Check each transformed link -// - Warn if any don't exist -``` - ---- - -## Troubleshooting - -### Build Fails: "Invalid frontmatter" - -**Cause:** File violates schema - -**Fix:** -```yaml -# Check: -- Is 'title' present? -- Is YAML syntax valid (spaces not tabs)? -- Are arrays formatted correctly? - -# Example invalid: -- tags: baby-ghosts, p0 # ❌ Missing brackets -+ tags: [baby-ghosts, p0] # ✅ Correct array syntax -``` - -### Wikilinks Showing Literally - -**Cause:** Plugin didn't run or had error - -**Check:** -```bash -# 1. Restart dev server -npm run dev - -# 2. Check plugin file exists -ls app/server/plugins/wikilink-transform.ts - -# 3. Check for errors in terminal -# Look for "error TS" messages - -# 4. Clear cache -rm -rf .nuxt -npm run dev -``` - -### Images Not Displaying - -**Cause 1:** Image not in `/public/img/` - -```bash -# Check: -ls public/img/image.jpg - -# If missing, add it: -cp path/to/image.jpg public/img/ -git add public/img/image.jpg -``` - -**Cause 2:** Wrong path in markdown - -```markdown -# Check these: -![[image.jpg]] # ✅ Correct (Obsidian syntax) -![](/img/image.jpg) # ✅ Correct (markdown) -![](/public/img/image.jpg) # ❌ Wrong (extra /public/) -``` - -### Git Conflicts - -**Prevention:** -- Pull before editing -- Work on different files -- Push frequently - -**Resolution:** -- See OBSIDIAN_SETUP_GUIDE.md → "Handling Conflicts" - ---- - -## Future Enhancements - -### Backlinks Display - -Show which articles link to current article: - -```vue -
-

Referenced by:

-
    -
  • - - {{ article.title }} - -
    • -
-
-``` - -### Link Validation at Build - -Fail build if broken wikilinks detected: - -```typescript -// In plugin: -const allSlugs = /* get all article slugs */ -wikilinks.forEach(link => { - const slug = wikilinkToSlug(link) - if (!allSlugs.includes(slug)) { - throw new Error(`Broken wikilink: ${link}`) - } -}) -``` - -### Graph Visualization - -Show article connections as interactive graph: - -``` -Communication Norms - ↓ - / | \ - ↓ ↓ ↓ -M.Guide Peer Support Bylaws -``` - ---- - -## Maintenance - -### Regular Tasks - -**Weekly:** -- Check for broken images (audit script) -- Review commit messages (consistency) - -**Monthly:** -- Run full build test (`npm run generate`) -- Test on staging server -- Backup Forgejo repository - -**Quarterly:** -- Review plugin versions (Obsidian Git, etc.) -- Update dependencies if needed - -### Updating Obsidian Vault Config - -Only need to commit `.obsidian/` folder if config changes: - -```bash -# Check what changed -git status - -# If app.json changed: -git add content/articles/.obsidian/app.json -git commit -m "Update Obsidian vault settings" -git push - -# Other users pull and get new settings -``` - ---- - -## References - -- **Nuxt Content v3:** https://content.nuxt.com -- **Nuxt:** https://nuxt.com -- **Nitro:** https://nitro.unjs.io -- **Obsidian:** https://obsidian.md -- **Obsidian Git:** https://github.com/Vinzent03/obsidian-git - ---- - -**Last Updated:** November 2025 - -**Maintainer:** Wiki-GhostGuild Team diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md deleted file mode 100644 index 5eecb2e..0000000 --- a/docs/TROUBLESHOOTING.md +++ /dev/null @@ -1,564 +0,0 @@ -# Troubleshooting Guide - -**For:** Wiki-GhostGuild Content Contributors - -Common issues and solutions. - ---- - -## Obsidian Issues - -### Obsidian Won't Open Vault - -**Symptom:** "Vault not found" or error when opening folder - -**Solutions:** - -1. **Check path:** Make sure you're opening the exact right folder - ```bash - # Should be this: - /path/to/wiki-ghostguild/content/articles/ - - # Not this: - /path/to/wiki-ghostguild/ # Parent folder - /path/to/wiki-ghostguild/content/ # Wrong subfolder - ``` - -2. **Full path issues:** On Mac, use full path starting with `/Users/` - ``` - /Users/yourname/Sites/wiki-ghostguild/content/articles/ - ``` - -3. **Permissions:** Make sure you have read/write access - ```bash - ls -ld /path/to/wiki-ghostguild/content/articles/ - # Should show: drwxrwxr-x (or similar with r+w) - ``` - -4. **Restart Obsidian:** Close completely and reopen - ---- - -### Wikilinks Showing as Red (Broken) - -**Symptom:** `[[Page Name]]` appears in red in Obsidian - -**Causes & Solutions:** - -1. **Typo in page name** - ``` - ❌ [[Communication Norms]] - Missing full title - ✅ [[Communication Norms Document for Game Studios]] - ``` - → Links must match article titles exactly - -2. **Title in frontmatter doesn't match** - ```yaml - # In article file: - --- - title: "Communication Norms Document for Game Studios" - --- - - # Then this works: - [[Communication Norms Document for Game Studios]] - - # But this doesn't: - [[Communication Norms]] # Partial match doesn't work - ``` - -3. **Cache issue** - - Close Obsidian completely - - Wait 10 seconds - - Reopen - - Wikilink should show as blue now - -4. **Check article exists** - - Open Graph view: Left sidebar → "Graph" tab - - Search for the article title - - If not there, article file is missing or title is wrong - ---- - -### Images Not Saving - -**Symptom:** Paste image, nothing appears or goes to wrong location - -**Solutions:** - -1. **Check attachment folder setting** - - Settings → Files & Links - - "Attachment folder path" should be: `../../public/img` - - If different, change it back - -2. **Folder doesn't exist** - ```bash - # Check: - ls /path/to/wiki-ghostguild/public/img/ - - # If not there, create: - mkdir -p /path/to/wiki-ghostguild/public/img/ - ``` - -3. **Try again** - - Paste image: `Cmd+V` (Mac) or `Ctrl+V` - - Should prompt for filename - - Edit if needed and confirm - - Image should appear and be saved to `/public/img/` - -4. **Check permissions** - ```bash - ls -ld /path/to/wiki-ghostguild/public/img/ - # Should be writable (w flag) - ``` - -5. **Restart Obsidian** - - Close completely - - Reopen vault - - Try pasting again - ---- - -### Obsidian Git Not Working - -**Symptom:** Obsidian Git plugin not appearing or not committing - -**Solutions:** - -1. **Plugin not enabled** - - Settings → Community plugins - - Search "Obsidian Git" - - Toggle ON if disabled - -2. **Restricted mode** - - Settings → Community plugins - - If "Restricted mode ON" shows, click toggle - - Enable plugins - - Refresh - -3. **Git not installed** - ```bash - # Check if git is available: - which git - # Should show: /usr/bin/git or similar - - # If not, install: - # Mac: brew install git - # Windows: Download from git-scm.com - ``` - -4. **Not in git repository** - ```bash - # Check: - cd /path/to/wiki-ghostguild - git status - - # Should show branch info, not "fatal: not a git repository" - ``` - -5. **Configure git identity** - ```bash - git config user.name "Your Name" - git config user.email "your@email.com" - ``` - -6. **Reload plugin** - - Settings → Community plugins → Obsidian Git → Reload - ---- - -## Git Issues - -### Can't Push (Remote Rejection) - -**Symptom:** "Permission denied" or "rejected" when pushing - -**Causes:** -1. Not authenticated to Forgejo -2. Remote URL is wrong -3. Branch is wrong - -**Solutions:** - -1. **Check remote URL** - ```bash - cd wiki-ghostguild - git remote -v - # Should show: - # origin https://your-forgejo.com/org/wiki-ghostguild.git - ``` - -2. **Fix if wrong** - ```bash - git remote set-url origin https://your-forgejo.com/org/wiki-ghostguild.git - git push - ``` - -3. **Authenticate to Forgejo** - - Generate personal token (Forgejo settings) - - Use token as password when git prompts - - Or set up SSH key - -4. **Check branch** - ```bash - git branch - # Should be on 'main' (or whatever default branch) - ``` - ---- - -### Merge Conflict - -**Symptom:** "CONFLICT" in Obsidian Git or error when pulling - -**Solutions:** - -1. **See conflict file** - - Look for `conflict-files-obsidian-git.md` - - Or use `git status` to see conflicted files - -2. **Resolve conflict** - ```markdown - # Find conflict markers: - <<<<<<< HEAD - Your version (what you wrote) - ======= - Their version (what they wrote) - >>>>>>> main - - # Delete one section and keep what's correct - # Or merge both if both are needed - # Remove the markers: <<<<, ====, >>>> - ``` - -3. **After resolving** - ```bash - # Mark as resolved - git add file-name.md - - # Commit the resolution - git commit -m "Resolve conflict in file-name.md" - - # Push - git push - ``` - -4. **Prevent future conflicts** - - **Pull before editing:** Start work each day with `git pull` - - **Work on different files:** If both editing, use different articles - - **Push frequently:** Don't let changes pile up - ---- - -## Building Issues - -### Build Fails: "error TS..." - -**Symptom:** `npm run generate` shows TypeScript errors - -**Solutions:** - -1. **Check file syntax** - ```bash - # Errors show file path and line number - # Fix the TypeScript error mentioned - ``` - -2. **Clear cache and try again** - ```bash - rm -rf .nuxt .output - npm run generate - ``` - -3. **Check dependencies** - ```bash - npm install - npm run generate - ``` - ---- - -### Build Fails: "Invalid frontmatter" - -**Symptom:** Build error about article YAML - -**Solutions:** - -1. **Check YAML syntax** - ```yaml - # ✅ Correct syntax - --- - title: "My Article" - tags: - - tag1 - - tag2 - --- - - # ❌ Common errors - tags: tag1, tag2 # Wrong - should be array with brackets - title: My Article # Missing quotes (usually ok, but can cause issues) - author "Name" # Missing colon - ``` - -2. **Validate YAML online** - - Copy frontmatter to https://www.yamllint.com - - Fix any errors it shows - -3. **Check required fields** - ```yaml - # Minimum required: - --- - title: "Article Title" - --- - - # All other fields are optional - ``` - ---- - -### Build Fails: "No such file" - -**Symptom:** "Cannot find module" or "ENOENT" error - -**Solutions:** - -1. **Check file exists** - ```bash - ls app/server/plugins/wikilink-transform.ts - ls content.config.ts - ``` - -2. **Check for typos in imports** - - Look at error message for exact path - - Make sure it matches actual file - -3. **Reinstall dependencies** - ```bash - rm -rf node_modules package-lock.json - npm install - npm run generate - ``` - ---- - -### Dev Server Slow / Hot Reload Not Working - -**Symptom:** Changes take a long time to appear, or don't appear - -**Solutions:** - -1. **Restart dev server** - ```bash - # Stop: Ctrl+C - npm run dev - ``` - -2. **Clear cache** - ```bash - rm -rf .nuxt - npm run dev - ``` - -3. **Port conflict** - ```bash - # If port 3000 taken: - npm run dev -- -p 3001 - # Then visit: http://localhost:3001 - ``` - -4. **File too large** - - If a single article is very large (>10,000 lines) - - It may reload slowly - - Consider splitting into multiple articles - ---- - -## Deployment Issues - -### Website Shows Old Content - -**Symptom:** Changes pushed but don't appear on live site - -**Causes:** -1. Build not triggered -2. Cache not cleared -3. Deployment not complete - -**Solutions:** - -1. **Force rebuild on server** - ```bash - cd wiki-ghostguild - git pull - npm run generate - # Restart web server - ``` - -2. **Clear server cache** - - Check hosting provider docs - - Usually: Clear CDN cache or restart server - -3. **Check deployment status** - - Look at CI/CD pipeline status - - Check if build completed successfully - ---- - -## Networking Issues - -### Can't Clone Repository - -**Symptom:** "Permission denied" or authentication fails - -**Solutions:** - -1. **Set up SSH key (recommended)** - ```bash - ssh-keygen -t ed25519 -C "your@email.com" - # Add public key to Forgejo settings - git clone git@your-forgejo.com:org/wiki-ghostguild.git - ``` - -2. **Or use HTTPS with token** - ```bash - # Generate personal token in Forgejo - git clone https://your-forgejo.com/org/wiki-ghostguild.git - # Use token as password when prompted - ``` - -3. **Internet connection** - - Check you have internet - - Try `ping google.com` - ---- - -### Port Already in Use - -**Symptom:** `npm run dev` fails with "port already in use" - -**Solutions:** - -```bash -# Find what's using the port -ps aux | grep nuxt -ps aux | grep node - -# Kill the process (replace 12345 with PID) -kill -9 12345 - -# Or use different port -npm run dev -- -p 3001 -``` - ---- - -## Article Issues - -### Frontmatter Missing After Editing - -**Symptom:** Content looks corrupted in Obsidian - -**Solutions:** - -1. **Check file** - ```bash - head -20 content/articles/article-name.md - # Should start with: - # --- - # title: ... - ``` - -2. **Recover from git** - ```bash - git checkout content/articles/article-name.md - # Reverts to last committed version - ``` - -3. **Check git status** - ```bash - git status - # Should show what's changed - ``` - ---- - -### Article Not Appearing in List - -**Symptom:** Article is in /content/articles/ but doesn't show up - -**Solutions:** - -1. **Check frontmatter** - ```yaml - --- - title: "Article Title" - published: true # Must be true or missing (default true) - --- - ``` - -2. **Check accessibility** - ```yaml - # If accessLevel is wrong, won't show: - accessLevel: "member" # User must be logged in - - # Try public for testing: - accessLevel: "public" - ``` - -3. **Check file saved** - ```bash - git status - # If file shows modified, haven't committed yet - ``` - -4. **Rebuild** - ```bash - npm run generate - npm run preview - # Check at http://localhost:3000 - ``` - ---- - -## Getting More Help - -If not in this guide: - -1. **Check the docs:** - - `OBSIDIAN_SETUP_GUIDE.md` - User guide - - `TECHNICAL_ARCHITECTURE.md` - How it works - -2. **Check error message:** - - Copy exact error - - Search online - - Try suggestion from error - -3. **Check logs:** - ```bash - npm run dev 2>&1 | tee build.log - # Look for warnings/errors - # Look for file paths that don't exist - ``` - -4. **Ask team:** - - Slack/Discord - - Comment in pull request - - Email team lead - ---- - -**Remember:** Most issues are related to: -- ❌ Wrong folder path -- ❌ Missing git configuration -- ❌ Typo in article title -- ❌ Stale cache - -99% of the time, one of these fixes it: -1. `rm -rf .nuxt && npm run dev` -2. `git pull` -3. `npm install` -4. Restart Obsidian -5. Restart terminal - ---- - -**Last Updated:** November 2025 diff --git a/nginx.conf b/nginx.conf index 08d38a0..d03023a 100644 --- a/nginx.conf +++ b/nginx.conf @@ -53,6 +53,30 @@ http { access_log off; } + # Homepage: inject OG meta tags + CSS + location = / { + proxy_pass http://outline; + + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Accept-Encoding ""; + + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # OG tags after so they appear before Outline's own tags + sub_filter '' ''; + + # CSS injection (must redeclare; sub_filter doesn't inherit across location blocks) + sub_filter '' ''; + + sub_filter_once on; + sub_filter_types text/html; + } + # Reverse proxy to Outline with CSS injection location / { proxy_pass http://outline;