jennie/wiki_ghostguild
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit

Browse source
This commit is contained in:
Jennie Robinson Faber 2025-11-11 19:12:21 +00:00
commit 92e96b9107
85 changed files with 24969 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

523
docs/OBSIDIAN_SETUP_GUIDE.md Normal file
View file

@ -0,0 +1,523 @@
# 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:**
```
<type>: <subject>
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 <PID>
# 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!

344
docs/README.md Normal file
View file

@ -0,0 +1,344 @@
# 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

607
docs/TECHNICAL_ARCHITECTURE.md Normal file
View file

@ -0,0 +1,607 @@
# 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
<div class="backlinks">
<h3>Referenced by:</h3>
<ul>
<li v-for="article in backlinks">
<NuxtLink :to="`/articles/${article.slug}`">
{{ article.title }}
</NuxtLink>
</li>
</ul>
</div>
```
### 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

564
docs/TROUBLESHOOTING.md Normal file
View file

@ -0,0 +1,564 @@
# 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