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

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:

---
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:

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:

![[meeting-workflow-diagram.png]]

Or with alt text:

![[meeting-workflow-diagram.png|Workflow for facilitating meetings]]

Code Blocks

Standard markdown fenced code blocks work great:

```python
def hello_world():
    print("Hello, GhostGuild!")
```

Tables

| 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:

   <<<<<<< 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:

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

# 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

# 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

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

   [[P0 - Communication Norms]]
   ![[diagram.jpg]]
   

2. At build time, the Nitro plugin transforms to:

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