# 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