Markdown
First, I decided to use Markdown (.md) files. GitHub will render these files, allowing you to style your D&D notes and add detail like images, links, etc. Markdown is easy to use and GitHub provides a great guide with examples. Check it out here for more.
I’m a visual person and artwork inspires most of my setting. Using GitHub and markdown, I’m able to render images with nothing more than a link to that image on the web. No hassling with downloading and re-uploading. No hassling with upload limits per subscription tier.
As with any creation that’s not yours, please be respectful and put in effort to credit the creator. In my repository, I’ve created a procedure for this very thing.
If you name a file README.md, it will render without having to open it. This is great for an overview of whichever directory you’re in. Above is an example of one of my kingdoms. You can head into the Locations or Settlements folders. But the README.md file in this folder is rendering itself below as a nice overview of the entire kingdom.
Visual Studio Code
To edit the files, I prefer Visual Studio Code. You can view the preview side-by-side (⌘K V) to see rendered markdown as you edit. I also use the Markdown All in One extension. It has many features but the nicest is a tool that auto-generates a table of contents on any files you want. Markdownlint also provides tools for formatting markdown with best practices. See the below example of side-by-side preview and a generated table of contents.
Advanced Code Snippets
In my D&D notes, many of the articles have a similar structure. I wanted a template for “characters”, for instance. Using code snippets, this was easy. A code snippet allows you to type a few characters and trigger and entire template to appear. See the video here. Code snippets allowed me to move much faster. I also have snippets for creating factions and other useful templates.
Version Control
This is likely a new concept for Dungeons Masters. But GitHub’s major power is version control. There’s a nice process for making changes. You can bypass it but stay with me for a moment.
As a Dungeon Master, I enjoy having everything documented. I may never use it all but its fun to look back on old notes. Version control adds another layer of documentation. I now have a record of every change that I’ve made because I follow the process. I can review changes before finalizing them. I can retrieve old notes with ease that I removed at some point.
Version control adds another layer of organization, too. Branches can represent specific pieces of work, focusing my worldbuilding. Pull requests signify a big change to my world or notes. Looking back through pull requests is an easy way to understand the evolution of the world.
If you’re new to the process and GitHub, it might seem foreign at first. But give it an honest attempt. The benefits are incredible. If you’re stuck or have questions, comment here and I’ll try to help.
Complete Control
Unlike many other solutions, organizing your notes in GitHub is completely customizable. I create the files. I format the files any way that I’d like. I organize the files. At any time, I can change any of those processes. GitHub provides an assist rather than the entire solution.
For my purposes, I’ve started with the following top-level directories:
- Adventure Logs
- Atlas
- Characters
- Factions and Organizations
- History and Cosmology
I’m already thinking of other high-level directories that could be useful:
- Calendar
- Magic
- Meta
- Religion
The solution to this is mine and mine alone to solve. I like that about GitHub. I’m not confined to a pre-defined set of tools and organization structure. And at any time, I can change it. That presents its own challenges that I’ll discuss shortly.
Along with that control comes extra care. In my job as a software engineer, I’m working in GitHub every day. Given that’s the master copy of our source code, I treat work in GitHub with care and extra attention. The same goes for D&D. I’ve noticed I take my time and give extra care to what I’m adding and how I’m adding it.
Pitfalls
I’d be remiss if I didn’t mention any pitfalls of this approach. But in all honesty, they haven’t caused me any issues. The benefits have far outweighed the pitfalls.
Permissions
Managing permissions is all-or-nothing. Either someone has access to your repository or they don’t. There’s not a way to hide information outside of creating another private repository. So creating a “GM Only” section on an article isn’t achievable. You could create it and link off to your other repository but it seems redundant.
Linking
The ability to link relevant content is huge with D&D notes. My location might mention a character. So I’d want that article to have a link to that character. All linking with markdown is manual. Luckily, you can create relative links with ease:
[Keanu Reeves](/Characters/KeanuReeves.md)
If you know your structure, you can set these up even if the character doesn’t exist yet. Because you know where they will exist. These links will need updating if you change the organizational structure. That’s a big pitfall. But the manual work of adding links hasn’t bothered me, especially with code snippets.
Potential
There’s real potential with using GitHub to organize D&D. Along with what I’ve done so far, I can think of a few other ideas:
- Keeping adventures or session notes in a branch and waiting to merge until after you’ve run them. Nothing is canon until its happened.
- Using other GitHub features like Issues and Projects to focus on what needs worked on next.
- Open source worlds. Allowing the public to request changes or additions to your world. The pinnacle of collaborative worldbuilding.
In the end, GitHub has proven to be a tremendous tool for organizing my D&D game. And it’s only the beginning.
You can see my project here:
