Initial commit
This commit is contained in:
commit
92e96b9107
85 changed files with 24969 additions and 0 deletions
523
docs/OBSIDIAN_SETUP_GUIDE.md
Normal file
523
docs/OBSIDIAN_SETUP_GUIDE.md
Normal 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)
|
||||
|
||||
```
|
||||
|
||||
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!
|
||||
Loading…
Add table
Add a link
Reference in a new issue