Wiki-GhostGuild Documentation

Welcome to the documentation for the wiki-ghostguild content system.

---

Quick Links

Starting out? → Read OBSIDIAN_SETUP_GUIDE.md

Having problems? → Check TROUBLESHOOTING.md

Want technical details? → See TECHNICAL_ARCHITECTURE.md

---

Documentation Structure

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

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

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

   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

   npm run dev
   # Visit http://localhost:3000
   

---

Key Concepts

Wikilinks

Obsidian native linking syntax:

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

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

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

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
• Having issues? Check TROUBLESHOOTING.md
• Want to learn more? Read 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