One of my side-projects is working on a novel type of Inform 7 documentation focused on showing Inform code next to examples of how they affect gameplay. I call the project “Inform 7 at Play”:
Right now, the documentation exists as a GitHub repo containing README.md files. This works relatively well, as GitHub renders the files as HTML, and even has some rudimentary Inform 7 context coloring for code samples. It has a few problems, however, most of which are hard to solve because GitHub doesn’t allow the application of custom CSS in rendered MarkDown files.
The main problems are:
On mobile browsers, the code doesn’t text wrap, and since Inform has some long “paragraphs” without linebreaks many code samples are unreadable
I’d love to make the “example” prompts look a little better. Do you think what I have is good enough?
GitHub in general looks a little forbidding to non-programmers who might not be used to scrolling down below the list of files or seeing the other GitHub controls
Does anyone have any great recommendations?
I have enabled GitHub pages:
And I think I can add an /assets/css/style.css file and disable wrapping… and other formatting but it seems like I lose the rudimentary Inform 7 styling this way, and also lose the ability to see where you are in the file tree or have global navigation. Also, the name of the repo at the top seems a bit ugly, although I guess I could make it a lot smaller with CSS as well.
I could ALSO do a more custom process… where I render and publish it using a GitHub action manually to my FTP server. Does anyone have any recommendations?
This might be a stretch, but I always thought Twine would be a great method to present documentation or “invisiclues” for other games; since you have access to all kinds of text formatting, CSS, image inserts, and you can hide and reveal sections and hyperlink around your document. And it can be distributed as a downloadable HTML or posted online for browser perusal.
I don’t know if this would work, but I wonder if you could embed a playable interactive snippet from Borogove.io in a Twine document. (Which obviously would only work with an internet connection.)
I don’t quite understand - you say GitHub Pages doesn’t support CSS, but then you yourself confirm that it does. GitHub Pages uses Jekyll to convert the Markdown to static HTML pages using templates and CSS, you can make it look like anything you want. If you know enough to make your own website on an FTP server, that is.
It seems you’ve enabled one of the default GitHub templates on your page, and that’s why the repo name is on the top, etc. You can customize that a bit with a CSS file, but you can also just override the whole thing. GitHub Pages/Jekyll is very customizable. I host my blog there as well, and all my blog posts are just Markdown.
Fully concur and agree with Hanon; in particular the Chapbook library (“story format”) look well-tailored for documentation, and not only documentation…
for example, is a perfect tool for tabletop RPG’s masters, adding a mersenne twister RNG for the most discriminating players, and even a “hilite table row/column” for the most discriminating masters, and the ultimate interactive master/player’s manual became clear…
I agree with Tobias, using a template (or creating your own) for Jekyll or Hugo is very easy. Or you could look at other tools designed specifically for documentation, Sphinx is a very popular one. Welcome — Sphinx documentation (sphinx-doc.org)
Sorry I was unclear. It was just the raw github pages where I don’t have the ability to edit CSS. I definitely realize I can use Jekyll for GitHub pages. I guess it’s flexible enough for me to add some navigation or something. The only thing I was saying seems lost in Jekyll is the Inform 7 syntax highlighting.