Github Pages Info

UInput | Github Pages | Documentation

Github pages generation

This guide is more about the specifics of my implementation as there are plenty of guides out there about setting up a github pages repo.

Starting under the assumption that you have the repo setup and ready to go, here is the way that I have my workflow setup;

All of the html files on this website (including this one) were generated from markdown using pandoc. This provides a number of speed advantages as I don’t have to be intimately familiar with all of the ever changing html/css standards.

Despite the files “only” being markdown files you may have noticed a number of features that markdown does not have native support for like;

This is mainly achieved through the use of the pandoc.css file. The containers for these files are inserted into the files via a number of replacement checks.

For example instead of typing out or copy-pasting the entirety of a “footer” file you just have to add %foot% at the end of the markdown file that you are working on and the build system will replace %foot% with the contents of which contains the footer template used on this website.

This is accomplished by the This script takes an JSON file as input where each key/value pair descirbes a possible replacement. An example of the format for this file and the options available (like referencing file content) are describe in the readme.


Quicker prototyping

While writing this article I wanted to insert the fontAwesome “copy” icon you see in the Limitiations section below (and code blocks below). Instead of going back through each page and making sure they are able to use them I can simply modify the scripts.htm file and add the font awesome javascript and the code to add a copy option to each code block.

Nested replacement

You can have replacements happen within other replacements for example %favicon​% is used to insert the favicon, here is the frags.json key/value pair (and the %baseurl​% value referenced in favicon);

"favicon": "<link rel=\"icon\" type=\"image/png\" href=\"\"/>",
"baseurl": "",

The end result looks like;

<link rel="icon" type="image/png" href="">

Multiplication and other functions

You can use the following notation to place a fragment N number of times;


Where %example% is set to Example would result in;



Meta discussion of the templating system

Placing literal %value% (the value of the replacement in a code block) is difficult to accomplish currently because the replacement is very simplistic and it’s basically just a find and replace.

If you’re insterting the value into actual text like %footer% you can add an HTML comment to prevent htmlgrep from finding it. Code blocks will (as far as I can tell) literally render everything within them so you can’t use HTML comments to the same effect.

You can work around this by finding a zero space character (click to copy) to the same effect; %footer​%

If you’re going to use this type of system long term you should install something that makes zero space characters more visible. vscode-gremlins is a great way to do this.

Local testing

Right now local testing is a bit of a pain. Currently there is a and a that use different frags.json files in order to make local testing easier. Simply sets the %baseurl​% value to be the filepath instead of the domain name.

It’s on my TODO list to update it so that you don’t have to maintain two frags.json files but it’s pretty low on my current TODO list.


To learn how things work, learn why things are done the way that they are. This is definetly a “reinventing the wheel” scenario but I’m just here to have fun and learn as much as I can.