|
| 1 | +# Contributing to Valdris |
| 2 | + |
| 3 | +Thank you for your interest in contributing to Valdris! This collaborative D&D campaign world grows richer with every contribution. Whether you're adding a mysterious ruin, crafting an NPC, or expanding the lore, your creativity helps make Valdris a living world. |
| 4 | + |
| 5 | +## 🌟 Quick Start |
| 6 | + |
| 7 | +1. **Fork the repository** on GitHub |
| 8 | +2. **Clone your fork** locally |
| 9 | +3. **Create a feature branch** (`git checkout -b feature/your-addition`) |
| 10 | +4. **Make your changes** following the guidelines below |
| 11 | +5. **Test your changes** in both Obsidian and browser |
| 12 | +6. **Commit with a clear message** (`git commit -m "Add: The Whispering Forge ruins"`) |
| 13 | +7. **Push to your fork** and submit a Pull Request |
| 14 | + |
| 15 | +## 📝 Content Guidelines |
| 16 | + |
| 17 | +### General Principles |
| 18 | + |
| 19 | +- **Maintain consistency** with existing lore and themes |
| 20 | +- **Keep it collaborative** - leave hooks for other contributors |
| 21 | +- **Think modular** - content should work standalone or integrated |
| 22 | +- **Stay system-agnostic** in lore (mechanics can be D&D 5E specific) |
| 23 | +- **Be inclusive** in your writing and worldbuilding |
| 24 | + |
| 25 | +### Writing Style |
| 26 | + |
| 27 | +- **Present tense** for descriptions ("The tower stands..." not "The tower stood...") |
| 28 | +- **Active voice** when possible |
| 29 | +- **Show, don't tell** - use sensory details |
| 30 | +- **Leave mysteries** - not everything needs explaining |
| 31 | +- **Player perspective** - no secret DM information in main content |
| 32 | + |
| 33 | +## 🔗 Link Formatting |
| 34 | + |
| 35 | +### For GitHub Pages / Web Viewing |
| 36 | + |
| 37 | +Since we maintain both an Obsidian vault and a web version via GitHub Pages, please follow these linking guidelines: |
| 38 | + |
| 39 | +#### Internal Links |
| 40 | +```markdown |
| 41 | +<!-- Good - Full path from root --> |
| 42 | +[Grimhaven](Settlements/Grimhaven.md) |
| 43 | +[Tinker-Priests](Factions & Organizations/Tinker-Priests.md) |
| 44 | + |
| 45 | +<!-- Bad - Assumes file is in root --> |
| 46 | +[Grimhaven](Grimhaven.md) |
| 47 | +``` |
| 48 | + |
| 49 | +#### From Subdirectories |
| 50 | +When linking from files in subdirectories: |
| 51 | +```markdown |
| 52 | +<!-- From Settlements/Grimhaven.md --> |
| 53 | +[Thymeris the Golden](../Architect Ruins/Thymeris the Golden.md) |
| 54 | +[Welcome](../Welcome.md) |
| 55 | +``` |
| 56 | + |
| 57 | +#### Non-Existent Links |
| 58 | +If linking to planned but not-yet-created content: |
| 59 | +```markdown |
| 60 | +<!-- Remove the .md extension --> |
| 61 | +The mysterious [Order of the Silver Key] guards ancient secrets... |
| 62 | +``` |
| 63 | + |
| 64 | +### File Naming Conventions |
| 65 | + |
| 66 | +- Use descriptive names: `The Singing Spires of Kelathon.md` not `spires.md` |
| 67 | +- Spaces are fine: `Architect Ruins.md` not `architect-ruins.md` |
| 68 | +- Maintain consistent capitalization |
| 69 | +- Group related content in folders |
| 70 | + |
| 71 | +## 📁 Directory Structure |
| 72 | + |
| 73 | +``` |
| 74 | +Valdris/ |
| 75 | +├── Adventures/ # Ready-to-run quests and campaigns |
| 76 | +├── Architect Ruins/ # Major ancient sites |
| 77 | +├── Economics & Trade/ # Commerce and economy |
| 78 | +├── Factions & Organizations/ # Groups and societies |
| 79 | +├── Lore/ # History and world information |
| 80 | +├── Music/ # Songs and musical culture |
| 81 | +├── NPCs/ # Notable characters |
| 82 | +├── Player Resources/ # Character creation and player info |
| 83 | +├── Political Systems/ # Governance structures |
| 84 | +├── Regions/ # Geographic areas |
| 85 | +├── Settlements/ # Cities, towns, villages |
| 86 | +├── Social Systems/ # Culture and society |
| 87 | +├── Technology/ # Architect devices and innovations |
| 88 | +└── Templates/ # Templates for new content |
| 89 | +``` |
| 90 | + |
| 91 | +## 🏷️ Tagging System |
| 92 | + |
| 93 | +Use consistent tags to help with organization: |
| 94 | + |
| 95 | +- `#location` - Physical places |
| 96 | +- `#npc` - Characters |
| 97 | +- `#faction` - Organizations and groups |
| 98 | +- `#lore` - Historical or world information |
| 99 | +- `#quest` - Adventure hooks and missions |
| 100 | +- `#item` - Artifacts, treasures, equipment |
| 101 | +- `#architect` - Related to ancient technology |
| 102 | +- `#recent-awakening` - Current events |
| 103 | + |
| 104 | +## ✅ Contribution Checklist |
| 105 | + |
| 106 | +Before submitting your PR, ensure: |
| 107 | + |
| 108 | +- [ ] Links use full paths from vault root |
| 109 | +- [ ] New content has appropriate tags |
| 110 | +- [ ] Lore is consistent with existing material |
| 111 | +- [ ] File names follow conventions |
| 112 | +- [ ] No DM secrets in player-visible content |
| 113 | +- [ ] Tested in both Obsidian and browser |
| 114 | +- [ ] Spell-checked (especially "Valdris" not "Valderis") |
| 115 | +- [ ] Added to relevant indexes or navigation |
| 116 | + |
| 117 | +## 🎨 Types of Contributions |
| 118 | + |
| 119 | +### New Locations |
| 120 | +- Include physical description |
| 121 | +- Add cultural/political context |
| 122 | +- Create 2-3 adventure hooks |
| 123 | +- Link to relevant factions/NPCs |
| 124 | + |
| 125 | +### NPCs |
| 126 | +- Provide appearance and personality |
| 127 | +- Include motivations (public and secret) |
| 128 | +- Add connections to places/factions |
| 129 | +- Suggest how to use in games |
| 130 | + |
| 131 | +### Adventures |
| 132 | +- Clear objectives and hooks |
| 133 | +- Scalable difficulty options |
| 134 | +- Multiple possible outcomes |
| 135 | +- Connections to larger world |
| 136 | + |
| 137 | +### Lore Expansions |
| 138 | +- Build on existing mysteries |
| 139 | +- Add depth without closing doors |
| 140 | +- Include multiple perspectives |
| 141 | +- Reference existing content |
| 142 | + |
| 143 | +## 🐛 Reporting Issues |
| 144 | + |
| 145 | +Found something that needs fixing? Please [open an issue](https://github.com/offendingcommit/valdris/issues) with: |
| 146 | + |
| 147 | +- Clear description of the problem |
| 148 | +- Location (file path) where found |
| 149 | +- Suggested fix if you have one |
| 150 | +- Label appropriately (bug, inconsistency, typo, etc.) |
| 151 | + |
| 152 | +## 💬 Getting Help |
| 153 | + |
| 154 | +- Check existing content for examples |
| 155 | +- Review recent PRs for style guidance |
| 156 | +- Open an issue with questions |
| 157 | +- Tag your PR as "needs feedback" if unsure |
| 158 | + |
| 159 | +## 📄 License |
| 160 | + |
| 161 | +By contributing, you agree that your contributions will be licensed under the same [CC BY-SA 4.0](LICENSE) license as the rest of the project. |
| 162 | + |
| 163 | +## 🙏 Thank You! |
| 164 | + |
| 165 | +Every contribution makes Valdris more vibrant and exciting. Whether you're adding a single tavern or an entire region, you're helping create something special for the entire D&D community. |
| 166 | + |
| 167 | +Happy worldbuilding! 🎲 |
0 commit comments