Portfolio Update / Static site generation

I have been thinking for a while to update my portfolio site, and I finally got round to doing it today.

I had several requirements:

• Minimal and easy to read
• Flexible enough to present the things I want
• Easy to update
• Entirely static and no JavaScript (or as close as possible)

Before we go through how the requirements were met I first need to introduce the systems already in place.
I use nginx for serving web pages, and I have a 'jhp' service running on my server that does server side rendering in JavaScript (as opposed to PHP, which I despise). When editing content for any of the subdomains I use a development environment integrated directly with the server, it is called opal.

What comes to mind when you think of minimal and easy to read when using your computer. At least for me, straight to my mind are the various TUI's of terminal applications. The (normally) restricted colors that can be output to the tty, and the fixed column width were the ideas that I chose to emulate.
I chose a fixed width of 80 characters, viewing it on both my smartphone and laptop both were a pleasant experience. I have a base text color of white, links being blue to distinguish them from the text, and have titles be offwhite to distinguish them from the text not only by size as I was having issues telling them apart.
There is one more color present on every page, which is used on the menu to distinguish which page is the current page within being viewed, I used orange for this.

The choices in the prior section are all well and good, but by themselves they provide a limited amount of utility when presenting, so some additional elements will have to be added.
Code blocks will be used throughout this site, and it would be more comprehensible if it had syntax highlighting, so I added the ability to highlight a code block. The highlighted block is hoisted out of line so that it does not confuse the overall theme.

int main(int argc, char** argv) {
    printf("Hello, world!\n");
    return 0
}

Some pages contain multiple sections that need not be read linearly. In order to present this information horizontal rules are made use of as they create a clear divide in the contents of the page.
Images are pretty much required to get some ideas across, at the moment they are just pasted in line, in future they should have a consistent sizing and styling applied to them.
One area that is a bit inconsistent with this styling is the Projects page as my previous portfolio site had a nice table to house the information for each of the projects listed. Be it that I was lazy or really think that it looks nice, I have chosen to keep it. Luckily the style does not stick out too starkly.

As mentioned prior I will be making use of opal to make changes to this site, this makes it rather trivial to make the site easy to update as I could have the save action automatically deploy changes I have made, this however is a pretty bad idea as I often save out of habit before things are actually complete and it could make the site inaccesible in the case of an error. So I opted to have the deployment be activated with a topbar menu item. Changes to the site only really require me to remember to click to deploy, and can catch any errors before they make the site inoperable.

This could be achieved by just not including any JavaScript, and refusing to have server generated content. This however would make it difficult to update which would violate our core tenets. So another approach is to have a preprocessing step in between, which takes some marked up static content and produces static content with it; this is what I opted for. The preprocessing language looks like so:

<##highlight("cpp")##> // For highlighting
int main(int argc, char** argv) {
    printf("Hello, world! %d\n", 11 < 10);
    return 0
}
</##>
<##snippet("name", "arg1", "arg2")##> // For copying over snippets (the body is copied into arg0)
body
</##>

 // For highlighting
int main(int argc, char** argv) {
    printf("Hello, world! %d\n", 11 < 10);
    return 0
}

These are just a couple of the available functions, there are several others; for getting posts, making a post, the sitemap, and a color theme.
I did not however manage to make it entirely static, as I wish to password protect certain areas within the site as they contain very identifying information. And also adding in the modification time was just too easy to do with jhp that I left it being regenerated each time.
Apart from these everything else is static, and as an added bonus each page is almost entirely self contained.

Edit (2023/03/26): I was experiencing a few issues with caching, so I made the last modification time also be statically generated, and made jhp only serve the locked pages instead of all of them.
This fixed the caching issue, but it did not make so much of a speed difference since the bulk of the time taken was the latency to the server, I halved this time, from between 50 and 70ms to around 30ms, by adding a cache rule onto cloudflare. The rule does not speed up the password protected pages, but that is a whole other issue due to authorisation being done per page. Anyway this was a nice change. I also made the images act similarly to code snippets to give a more cohesive feel.

Edit (2023/03/27): I have swapped a couple of words around and changed a little bit of the structure to make the post more readable.

last modified: Sun, 07 May 2023 13:04:06 GMT