Howdy there stranger! I am Gulluth, also known by those who dwell inside Vaarn's Interior as the Desolate Drifter. This here guide was prompted when that nomad fella’ named Graculus Droog asked me about how to go about creating an SRD for his new tee-tee-arr-pee-gee called Blood Heist. Ya see, I was the one that assembled all of them digital bits, them ones and zeros, into an order that can be fetched by ye browser and serialized straight through your optical nerves and into your brain; splain to ya’s on how to play his other game Vaults of Vaarn.
The following is a process on how I would set up a brand new SRD. This will outline the considerations I had which lead to the choices I made, and the steps I followed when creating the Vaults of Vaarn SRD. I will revise this guide as new details emerge from my fragmented memory, or for clairity based on feedback I receive.
- Public Facing. I was making this for my personal use, but I wanted others to benifit from my work so I wanted it to be open to the public.
- Free web hosting. I did not want to pay out of pocket to run the website.
- Everything in Git. I did not want to mess around with a database, or with backups. Git makes having multiple copies of everything very easy.
- Easy to update. The markup had to be light, so why not just use markdown.
- Collaborative. I wanted an easy way to add others to the project who had a shared interest in Vaarn.
- Automatic webstie deploys. Github Pages was built specifically for this.
-
A basic understanding of the markdown language.
-
You will need a github account to follow along with this guide. Don't be alarmed if git seems intimidating, you can do this whole process through the browser without knowing git. This process will be easier over the life of the project if you do understand git at a basic to intermediate level though, so I recommend learning github desktop.
Once you have your account on github you will want to consider the URL you want your SRD to be accessed by. If you regestered a new github account, and it is the name of your RPG, you might already be done with this step. For the VoV SRD Leo was not yet on Github, and I wanted the url to be https://vaarn.github.io. In order to create this URL I needed to create a github organization named "vaarn" where the git repository could be created. Pulling from memory the URL must match the userid or name of the organization for this to work.
Side note: You can use a custom domain for your SRD, but it still requires this step and the custom domain can be configured at a later time.
Next was creating a repo in the organization to hold the source code of the SRD. I was planning on hosting using github pages, which has specific requirements for the name of the repository, so I created a repo named vaarn.github.io. Go ahead and pre-populate it with a README.md when creating the repo. If you skipped this step, just create the file (from the repo homepage: add file > create new file) and put some markdown in it, even a simple "Hello, world!" is enough.
I have used a lot of static website generators, but most of them have an intermediate step that compiles the markdown to html that is then served from github pages. I was also looking for something light and easy for others to use that might not be familiar with the language ecosystems built around these other tools. There are popular website generators in Python, Ruby, Go, and Rust to name a few, and getting these toolchains working local can be hard for someone not familar with working with the development tools. Then I came across docsify, written in javascript, and renders the markdown in your browser directly without the intermediate pre-compile step of the other static website generators. This turned out to be a great solution. Installing docsify is as easy as adding the index.html from docsify to your own git repo(from the repo homepage: Add file > upload files), creating an empty file named .nojekyll, and enabling github pages.
Deploying to Github Pages is as easy as turning on a setting in the project's properties. Here is the thing, if you have followed all of these steps and the repo contains the files README.md, index.html, and the empty .nojekyll file. Once you enable this, the website should be live, Go check it out!
Now the process is simple, if you want to modify docsify settings you do so in index.html, if you want to add content to your srd, you edit README.md. If you do this through the github UI, as soon as you save your changes, they are live. If using a git client, after making changes locally, staging, committing, and pushing your branch, the changes will also be live.
The Vaults of Vaarn SRD Source Code is free under the terms of the Creative Commons Attribution-ShareAlike 4.0 International license. You can study this code to see how I assembled those bits together, and feel free to reach out to me on twitter, github, or itch.io if you have any questions.