344 lines
7.5 KiB
Markdown
344 lines
7.5 KiB
Markdown
# 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 → 
|
|
|
|
(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
|