Initial commit
This commit is contained in:
commit
92e96b9107
85 changed files with 24969 additions and 0 deletions
344
docs/README.md
Normal file
344
docs/README.md
Normal file
|
|
@ -0,0 +1,344 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue