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 footer.md which
contains the footer template used on this website.
This is accomplished by the htmlgrep.py. 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.
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.
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=\"https://samuelsebastian.dev/assets/favicon.png\"/>",
"baseurl": "https://samuelsebastian.dev",The end result looks like;
<link rel="icon" type="image/png" href="https://samuelsebastian.dev/assets/favicon.png">You can use the following notation to place a fragment N
number of times;
%example*2%Where %example% is set to Example would
result in;
ExampleExamplePlacing 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.
Right now local testing is a bit of a pain. Currently there is a
build.sh and a local_build.sh 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.