2018.12.30 by Josh Erb; 2070 words.
Being a mobile-focused Support Engineer at Mapbox means that I tend to focus on non-general languages and design patterns that are specific to proprietary platforms. The considerations and constraints are very different from something as sprawling and globbed together as the World Wide WebTM. But this doesn’t mean that I haven't been required to rub elbows with web development here and there.
My original website was up for about 8 months before I decided it needed new life. You can see the extremely simplistic site I initially made courtesy of the Internet Archive’s Wayback Machine. I made this site quickly and haphazardly during some downtime between jobs (no lie, I hand coded my resume bullets in vanilla html). It certainly shows. Although I don't expect very many people saw it in that state, I was unsatisfied with this first, naïve attempt at building a web page and was craving an excuse to get more exposure to some modern web development tools and systems.
In the interest of posterity, I want to use this inaugural blog post to walk through my motivations for redesigning the site and using the tools that I used.
I want to give credit where credit is due and run through a list of the tools I used to host, design and build the site in its current form. If you’re not interested in my long-winded justifications and (likely inaccurate) descriptions of these tools, the site is Open Source on GitHub where you can see the structure and code (warts and all) for yourself.
This piece hasn’t changed recently, but I think it’s worth documenting. I use Neocities to host this website. It’s a cheap solution (on their “supporter” plan it only costs me $5 a month to keep this site up and running) and it provides SSL support by default. This saves me from having to get tangled up in any of the minutia of dotting the ts and crossing the is for my basic configuration, which I think should generally be the point of a hosting service.
And I’ll be honest, there are other solutions I could have used. For example, Netlify has been getting some buzz lately. This can likely be attributed to the "Free for Open Source" tier in their pricing plan. However, Neocities will always hold a soft spot in my heart because they are also early adopters of IPFS[1] and advocate for a more permanent solution to how the web is structured and maintained.
To be perfectly blunt, CSS is an area of web-development that have absolutely no comfort with. I’ve known CSS and how it relates to HTML since my edgy days of editing my edgy MySpaceTM page[2] style back in Junior High/High School.
I knew that it would be faster for me to use a boilerplate CSS library and tailor it to my specifications that it would be to start wholly from scratch. But I didn’t want to use some big, ungainly, and wholly generic (as a result of its ubiquity) thing like Bootstrap.
No kidding, I literally searched the phrase minimal css boilerplate and was lucky enough to find Skeleton CSS. The library is small, clean and easy to get up and running with after you browse it’s documentation.
I didn’t want the library loading from an externally hosted server, and I also wanted to tweak certain elements like buttons to my liking, so I downloaded it added it my site’s assets and began to tweak away. In addition to the core modifications, there were also elements that I wanted to customize that weren’t already addressed by the framework. To keep things clean(ish), I implemented these changes as a separate CSS asset.
This is currently the primary thing about the site that I don’t like. This is a misleading way to state this, let me clarify: I am sometimes haunted at night by the thought that Google’s Fonts are so easy to use that one day their servers will go down, or the company will monetize it’s Font business more aggressively and suddenly millions of web pages (this one included) will look deformed and grotesque.
So yes, while I did momentarily fall in love with Roboto Mono and add it to this new and improved version of my site. I think I can accomplish a similar ascetic by other means once I get over the hump of understanding the best way to bundle a font and remove the external dependency. I’ve already put this one on my “minor skills to learn in the coming year” list (which I’m partially tracking on the repo).
Like CSS, JavaScript templating is another area that I do not feel extremely comfortable with. I know it’s a critical part to getting things running smoothly with a site generator - but I had no idea where to start. Don’t tell the project's maintainers this, but I didn’t put too much consideration into this and ultimately defaulted to Nunjucks because that’s what all of the examples in 11ty’s documentation were written in.
After starting this my site refactor, I found out about Moustache and the concept of “logic-less templates”. Personally, I found that Nunjuck’s suited my needs and made enough sense once I took the time to read the documentation a bit more closely. So I didn’t investigate, compare, or attempt to rewrite my layout templates after I learned about the other possible solution. That being said, no solution is ever final, so re-visiting my approach to templates might be worthwhile if I have time in the future. I’ll also note that this is the one area where I don’t feel that I’ve done my homework very well.
Based on my needs an interests, I knew that I didn’t want or need anything more complicated[3] than a static site generator. Selecting a generator actually proved to be one of the harder aspects of the project. I’ve had minor brushes with Jekyll in the past, and while I appreciate the lasting contributions it’s made to this area of web development it lacked a certain je ne sais quoi that I was looking for in terms of structure and usability.
At work I’ve had the pleasure of being able to use the extremely the sleek, and open-sourced Batfish library, but I decided against opting for this familiar tool for two reasons. First, if you are a barista and you spend all day making espresso, the last thing you want to do when you get some free time is spend it making more espresso. I wanted to get a sense of what else was out there and see if there were flexible and (most importantly) user friendly generators gaining traction outside my current circle.
Second, Batfish is lightweight, but it’s made with much beefier projects in mind. Hell, it’s used to maintain all of my current company’s sprawling documentation. I don’t expect my site will need to be nearly as dynamic or massive, so I want to keep things nice and simple. Preferably only needing to use a build and serve command when developing, with minimal configuration or tom foolery required to get things up and running.
At some point during my research, I came across 11ty. 11ty checked all my boxes, had clear documentation and examples, and seemed very easy to get up and running with one Saturday afternoon while I was browsing for tools.
I also have to be perfectly honest and admit that to get over the learning curve[4] I did a fair amount of cribbing from the eleventy-boilerplate blog put out by Dan Urbanowicz.
(👋 Thanks, Dan!)
It’s no fun designing and building a website without content. I had some lame, test content written when I first started working on the blog section, but it was uninspiring and I was having trouble seeing the bigger picture with just a handful of stand-in posts.
Fortunately, during the holiday break I had a moment of inspiration! When I was younger and traveled, I had maintained travel blogs. These old blogs were currently sitting precariously on 3rd party blogging sites that I didn’t control. At any moment this part of my personal digital history might disappear[5] and there would be no recourse for getting it back.
This prompted me to decide to migrate all of my old posts over to this new blog I was building. It also provided an ample opportunity to tweak my site's blog structure and design as I added more and more content to it. Round a corner here. Tweak a spacing there. Add a word count, just because I started to get curious along the way.
Now I’ve got Suburban Berber and Josh Has Gone French dated, tagged, and archived on this site. This site that I manage and style and I’m quite pleased with the look and feel of the posts. If you’re curious about my past experience living abroad or just want to see how different my writing style was years ago, feel free to click around. I pulled them over in the exact same state they were in (title typos and all), the only thing that’s changed is the style.
Overall it was a fun trip down memory lane, and I’m glad I had the thought and time to follow through.
Of course, even after putting all of this effort into polishing up the site, there are still things that are still squatting in the back of my mind that I’d like to improve. For posterity's sake, and to preempt any potential criticism from my peers, I’m going to list my primary nit picks here and now.
These are all the ones I’ve noted so far. When inspiration strikes, or I see something I want to change I try to add it as an issue to my repo. Since this site will only ever be maintained by yours truly, and even though I’m managing the site and related projects via GitHub, I’m not actively trying to follow best-practice code conventions (e.g. I have definitely committed to master more times than I have ever done in a professional setting).
My main goal is to make updates to the areas I want to improve, or use it as a learning tool to gain familiarity with a concept, tool or system, in a low-risk environment. I’m casually referring to this as a “Goldilocks Strategy” toward my site's development and maintenance.
I’ll be making minor tweaks to every piece until it all feels just right.
IPFS is a very interesting project that I’ve been following for the last few years. I won’t get into it because it’s tangential to this blog. But if thinking about how to improve the structural integrity of the system that currently stores an increasingly large share of all of humanity’s knowledge, communication, and creativity is your jam, I encourage you to check it out.
Don’t look for my MySpace page. It’s long gone, I assure you.
Don’t worry, I know that static-site generators can be extremely complicated if they want to be.
Just to clarify, this is definitely the result of my inexperience with web development and limited exposure to the structure and functionality of static-site generators.
Yes, I’m noticing that resilient systems and future-proofing my digital footprint appear to have become a re-occurring theme in this post.
{ #development #web }
<< words.