My New Site!

published: 2022-09-21
tags: misc

"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

My site generation script

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.