wiki_ghostguild/docs/OBSIDIAN_SETUP_GUIDE.md

# 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!