My New Site!
published: 2022-09-21
“Where’s that beautiful white page with a single GIF and the amazing photo of the totally not horrifying star of Trendy Talk, Trendi the Floating Face?” I here you say, well, making an actual real site was something I’ve been thinking for quite a while but I mostly held back because:
- It’s been a long time since I messed with HTML/CSS properly and some relearning would be required (and I was never great to begin with)
- I didn’t think I’d really have any content to put on it.
So what changed? Well, I went on an adventure with cloud storage that I decided to actually write about and post it over on friend HexDSL’s site (it’s also technically the first post on this one too now) which I’m aware isn’t amazing, but I actually enjoyed writing it so, combined with my wanting to do something somewhat productive as well, I thought “fuck it” and started down the path of finally making my own site.
(Re)Learning
Back down the HTML/CSS basics hole I went, mostly courtesy of Mozilla’s excellent web docs. For context, web design is something I dabbled with on and off forever but never really put a lot of consecutive learning in, so my knowledge was all over the place, especially with CSS. HTML of course, is fairly simple, mostly building blocks to later be transformed by CSS into something aesthetically pleasing, so CSS is where I spent most of my time really.
My intention from the start was keep this site fairly simple so to be honest, I still haven’t really took much a deep dive into anything, but I know more than before so that’s something!
Design
I wanted to keep it simple, but just how simple was the question. The first iteration was mostly just me playing with random elements so I’m not even going to count it. The last time I looked at HTML was probably just as HTML5 and CSS3 were just becoming a thing. I’d heard of various changes but I hadn’t really played them, I did know this wonderful thing called a flexbox existed though, so that’s where I started. The first real version of the site had the header at the top, the navigation on the left and the content mostly in the middle of the screen, each with a rounded box with a background colour. It was mostly fine but I found myself being annoyed playing with padding and margins to try and get thing where I wanted them, and on mobile it just didn’t look right at all. I spent too long on this design but it was fine.
Browsing through Mozilla’s web docs I had read about grids too so I
started a new CSS style to play with them, and I had a much better time.
First off, I decided I wanted the navigation at the top instead of the
side so I could leave the content as a focus point with no distractions
for reading. The next main change was removing the coloured boxes
surrounding the content, these were fine but I found that I liked the
much cleaner look not having them was. The grid layout let me position
everything much easier as well. I made a div wrapper tag to
encapsulate everything from the header to content, set the
grid-template-columns to three columns, the first and third
15% leaving the second at 70%. By leaving the two outside columns blank
it let me instantly centre the content easily without messing with
anything else, it’s great!
Colours were next, very important. I wanted something dark but not ridiculously dark. I went with a nice blue-grey, the previous version of site had a lighter colour for the old content boxes too. Link colour was something I thought for far too long before popping open a colour wheel and picking the opposite side of the background colour, easy, nice looking.
Lastly for the navigation bar, I just wanted it between the header
and the content so I popped it in a list, for easier generation mostly,
made it’s display inline-block to get it horizontal and
stuck a border-right to get the dividers.
I still haven’t decided what to do with the header. For now, I simply made it slightly larger than the other text, bold and spaced out the letters which at least makes it look a bit different to everything else. Will more than likely do something else with it.
I realise nothing I’ve is in any way complicated and there’s probably better ways of doing it but it worked for me, and I’ll still making some changes as I go, though feel free to contact me with any tips and such you might have.
Generation
Now here’s the fun part, where I probably spent most of my time! My site is statically generated. I spent some time thinking exactly how I’d go about generating it, I used projects like hugo before but I always felt like they were overcomplicating something simple, though that’s probably a side effect of trying to be everything for everyone. I had seriously considered writing my own generator form scratch but while I was mulling over the various aspects of that, and specifically converting markdown to markup, I thought “I’ll just pipe into pandoc” for that and come up with something for templating around it. Pandoc is wonderful project that lets you very easily convert various text formats but I’d only ever used it for quick conversions in the past and not thought much of it, I don’t even remember what I was looking up in docs when something caught my eye; “Templates.” As it turns out, pandoc has it’s own templating engine, it’s always nice when you find out a little tool you’ve used on and off for years is actually capable of far more. I’m sure basically everyone who uses pandoc a lot more than me already knew that but it was a surprise for me!
My work was cut down dramatically with this revelation. I spent some
time combing over pandoc’s templating engine and all the other switches
I never had use for before, like passing a YAML file full of useful
variables. If you’ve never used it before, pandoc’s HTML templates are
very simple: you create your template to pass to the pandoc
command via the --template=yourtemplate.html switch which
you can fill with variables by surrounding the variable name in $’s like
so: $myvariable$ These variables are taken either from a
file you can pass to pandoc with
--metadata-file=myfile.yaml and/or from the input markdown
file itself by creating a block at the top like this:
---
title: myTitle
date: 2022-09-20
myVar: myValue
---
My amazing blog post!Pandoc will complain if you don’t have a title variable
but it will still compile and simply use the filename as a default title
but otherwise, the variables are up to you. So as you can tell, pandoc
actually does the bulk of awkward work when it comes to making a static
site, I don’t know why I ever looked at anything else.
Next up was writing a bash script to actually go through and loop the
pandoc command through the content files. If it doesn’t
exist, the script starts by creating the “output” folder and it’s two
sub directories, “media” and “blog,” then deletes any old html files
from previous runs in the “output” folder and finally copies over the
CSS file. Now the actual generation gets started by first using two
find commands to get lists of the regular pages and blog
posts for pandoc to loop through while also building a temporary YAML
file for building the page that will list the blog posts by using
yq, which is like jq but for YAML, to grab the
“title” and “date” lines at the top of each blog file and appending them
to the temporary file. This part originally used a quick
sed command, though as I went on do more with the markdown
files, like generating RSS, it became it wasn’t the best solution so I
found that yq existed, which does mean my generation has a
dependency but I’m okay with it considering it greatly eases the work.
The blog pages are iterated through in the first loop while generating
the temporary file containing blog titles and the link to them, then the
second loop iterates through any regular pages, like the index page,
contact and of course the blog list, where it also passes the new file
so the template can create the list of posts. One small thing I added
for the pages loop was an if statement to check if a template with the
same name as the page exists which will then pass that instead of the
default page template so I can easily have custom template for certain
pages without having to add anything extra to the generation script.
The last bit of generation is the RSS feed. The feed header is saved
into a variable then the blog posts are looped through and the variable
gets all the <item> sections adding to it for each
post by using yq to grab the necessary information from
each source file then the closing RSS tags are added and the saved to
feed.rss file.
Finally the temporary file is removed and a “site generated!” message
is displayed, that’s it! Very simple, though I did add a little case
statement to catch command arguments. The first, “serve” starts up
python’s built in web server with
python3 -m http.server --directory output so my links will
work correctly and I can test the site properly, since all my links
start with a forward slash the stylesheet won’t work on sub directories
otherwise. The second possible command is “upload” which uses
rsync to upload the result to my actual server. However, I
did swap out the python server later when I decided I didn’t want the
“.html” suffix in my URLs. I use caddy as my web server (it’s
fantastic!) and I added a try_files statement to it to
return files without the suffix, so to test it locally I made a quick
Caddyfile and changed the python command to
caddy run --config Caddyfile to run caddy locally with a
config file that exists solely for this site.
There is still a lot I want to do and need to figure out, still deciding on the syntax highlighting style I went with, which is pandoc’s built pygments style with a colour or two changed, but overall I’d say I’m pretty happy with what I have so far so feel free to keep an eye here, or follow my rss feed for more posts from now on.