And oh, what a many-month-long dive it was.

I am a Perfectionist at heart, and there are a lot of Best Practices to follow, ones from which these shiny pearls are harvested.

TL;DR

Now, if you’ve come here to see the Attributions for the Creative Commons artwork used on this site – like :point_left: that one – they are down here.

But please … feel free to keep reading. The purpose of this entire post is to pay flattery to the articles, posts, resources, assets and Open Source toolkits which were there at my disposal when I built this blog.

I’ve done my darnedest to convey all the details in a way other than as a listicle or shower of bullet-points.

Inspiration

I’d been chomping at the bit to do a redesign of this thing here for many years. My old design – now lost to the Winds of Time – was *ahem* rather lack-luster. Trust me on this, folks; the Winds of Time can have it.

Then one day, I read a post about the copy-on-write internals of Ruby by Brandur Leach, and I became truly inspired.

I find the blog’s visual design to be a sublime blend of online content and classic newsprint layouts. The information density that it conveys, with its powerful heading, unassuming sidebar, dual-functioning gutters and seamless diagrams, is both magnificent and effective.

Yes, this was what I wanted.

I was further influenced by the strong watermark at the head of John Novak’s blog. I see a poetic balance of vector graphics and discretionary color, the spirit of which which I’ve shamelessly copied.

I appreciate David Clark’s choice of font families & sizing, and his generous use of whitespace. Varuna Jayasiri has a nice columnar layout with just enough color to call focus yet not be distracting. And Hack Cabin, opinionated in its use of strong colors, uses a good set of icons to punctuate metrics like the Word Count and Reading Time.

All of that, yeah. I want it all.

The Vision

I need me a Brochure for the Ages. A visual statement of Timeless Web Design. Something that would bring me more delight than the parade of very capable but otherwise ¯\_(ツ)_/¯ blog post templates that I see on a weekly basis as I catch up with “the Feeds”.

Sure, for most people it’s about getting the content out there, moreso than making it look “right”. But it would appear that I’ve got a fever, and the only cure is :smoking: rollin’ my own site. Fortunately, I have a smattering of design skills, and I have a friend in Hennie Farrow, my employer’s Head of Design, who had plenty of salient advice for me.

Oh, did I mention the Perfectionist thing? Yeah, I’m one of those.

So, let’s roll up our sleeves and get down to it, shall we?

Static Site Generator

I went with Jekyll. It’s got a long history, good documentation, it supports Markdown as a first-class citizen, and it’s Ruby.

Out of the box, Jekyll will use its Minima Theme. I needed a good set of training wheels to figure out their Template system, so I also plugged in their Minimal Theme. They are similar in name alone.

Of course once I’d gotten familiar with the Liquid DSL, I went and :smoking: rolled my own Theme. Various examples of date formatting and how to list all the posts, tags and categories (etc.) were of great help.

The core Plugins I chose for the Build were

I implemented a few Plugins of my own – such as my Day Calendar widget and Footnotes composer – with the guidance of Liquid for Programmers and the source code of the tools above.

Microformats

I want my content to be machine-readable in a shit-ton of different ways. Obviously, it’s gotta have a Sitemap and a robots.txt. Adding a humans.txt seems the polite thing to do.

Then, there’s an immense amount of scrape-worthy <metadata /> to be offered up, much of which is covered by joshbuchea/HEAD.

For instance, just off the top of my <head />, there’s

The HTML also provides some minimal ARIA markup, enough that the Web Accessibility Checker doesn’t compain too loudly. I declare Element roles where needed, and it is easy to apply the empty alt Attribute & aria-hidden techniques.

In the interest of being fair & balanced, there’s also an anti-Accesibility feature, as explained in Special Effects.

Major props out to ngrok. Their service is invaluable in projects like these. It allowed me to expose my private HTTP dev environment for public parsing and scrutiny.

And while we’re on the subject of meta-information … I authenticate the blog through keybase.io, and far as I’m concerned, my own work here falls under the Do What the Fuck You Want to Public License.

Markup

My blog follows a semblance of the recommended HTML5 semantics, with a <nav /> and <section />s and styled <ul />s galore. It’s interesting how even minor structural changes can impact machine-parseability, such as the way Safari Reader renders your site.

On the advice that markup like <article /> should never be styled, each semantic Element has an inner CSS “Wrapper” <div /> which shapes the container. This approach comes in real handy when it’s time to implement a Responsive Web Design.

This comparison of PX, EM and REM media queries led me to do virtually all the CSS sizing in EM units, including the scaling of SVG assets and pixel-pushing (hah) Elements around by multiples of 0.1em. EMs make everything scale just so darn nicely. The only places where PXs were indispensible were in border-widths and a touch of letter-spacing.

There are three major media breakpoints which trigger the page layout. I’ve even come up with nicknames for them:

  • “weensie” – less than 30em – likely a mobile Portrait mode, where real-estate concerns put font-size and padding at a premuim
  • “baseline” – up to 48em – a mobile Landscape mode, or any tablet-y reading experience; there’s room for a sidebar, the font-size can get kicked up, and content can flow to the screen’s right edge
  • “widescreen” – 60em and above – whereupon it’s viable to introduce fixed gutters and other columnar wizardry

Once you reach “widescreen” mode, paragraphs get constrained to an optimal line length, as covered in more detail under Font. Additional breakpoints above “widescreen” will gradually jack up the font-size to optimize for large-scale displays.

Now, whereas all the text in my CantRemember.com design scales fluidly using vh And vw units, that is an anti-pattern for a blog. Readers should be able to scale the font to whatever size suits their reading comfort.

Well, it just so happens that one side-effect of doing media queries with EM units is that increases in scale gradually trigger the lower breakpoints – at least in Chrome & Firefox, anyway. If you zoom in far enough while browsing from your laptop, you might just see “weensie” in action.

With all that deliberateness in place, it seemed reasonable to lock down the mobile viewport scale. Both Mozilla and Google provide good takes on this technique. I’d imagine folks have better things to do than pinch my pages.

Styling

Aside from the Responsiveness, there’s nothing special going on here. Everything stacks on top of normalize.css. I use BEM class-naming conventions and [attribute="behavior"] selectors. Those choices, and the use of SASS, keep it all from becoming a tangle.

And thank Goddess that SASS lets you put your @media selectors anywhere you damn well please.

The styling keeps mostly to the basics, like centering techniques and maintaining aspect ratio for <img />s. All of the Special Effects were implemented with native DOM methods, for which DevDocs is a fantastic reference. I also needed a few reminders of how to measure Element dimension and location.

When this site got built, there was growing adoption of neato-keen features like CSS Variables and Grid Layout. However, Can I Use told me that availability was still limited … whereas here I am, building a site that can be read comfortably using Lynx.

Okay, there is a bit of Flexbox – the modern spec, as opposed to the 2009 & 2011 variants – whose only job is to grant the <footer /> its own multi-column layout. But even with a good guide and applying just the basics, I fought enough battles against browser-specific quirks (I’m looking at *you*, Safari) that it was more reliable to go old-school :metal: for everything else. All without any uses of float, of course; I do have some principles …

Also, some judidious uses of Animation, nearly always with opacity. Thanks to the community, I can now use CSS Transitions and CSS Animations like a pro.

Iconography

As the Attributions below would suggest, this blog is thick with vector graphics. There are tools out there which I could have used to :smoking: roll my own Icon Font. But upon further consideration, naaah.

Throwing caution to the wind, I disregard support for SVG fallbacks and instead use the simple <img /> tag approach. A limited set of them get inlined during the Build because that instant-rendering rush is worth some per-page overhead.

I played around with implementing the “watermark” SVG as a CSS Background Image to colorize its stroke. However, would have required an inlining, lest the viewer’s eyes be assaulted with a solid rectangle of background color until the asset had downloaded. Again, naaah.

Font

The range of choices offered by Google Fonts is astounding.

I wanted a nice legible sans-serif <body /> font, so I went with the always-popular “Open Sans” … it is really easy on the eyes. Other families in the running were; Hind Guntur, Hind Siliguri, Mukta Vaani, Noto Sans, Nunito, Palanquin, Roboto & Raleway

Then, hmmmm … hey, maybe the <h1-6 /> Elements could use a bit of an accent. So I :smoking: rolled my own Font.

I did not roll my own Font.

I chose “Teko” … it’s clean, legible, and it has zing. Other families under consideration were; Alegreya Sans SC, Anton, Asul, Michroma, Ramabhadra, Secular One & Viga

“Open Sans” offers Italic style and Bold weight variants, which get loaded & leveraged with the @font-face declaration. There’s a very nice smoothness to a native italic font – the synthesized version isn’t as crisp. I’m hoping that after gzip and the Build’s glyph-shaking step, the reading experience is worth the load time.

“Open Sans” also offers some beautiful Light variants, but I felt they would bloat the site (ಥ﹏ಥ) . Instead, I settled on some fine-turning for Webfont Selection and Synthesis.

The “Bulletproof” @font-face syntax seems to be genuinely immune to bullets. And wouldn’t you agree there’s something charmingly 1920-ish about old-style Numerals?

Oh, and really? “Your Body Text Is Too Small”? I don’t think so :punch: . In widescreen layouts, my text scales up to 14pt. Yes, it can drop down to 11pt under mobile conditions, but, again, :punch: . I’ve applied some methods for controlling spacing at both the letter and word level, because I felt that subtle adjustments made a big difference in the paragraph flow.

Widescreen layouts – where the sidebar and gutters appear – have their content constrained to { max-width: 65ch }, dead center of the range suggested when writing CSS with Accessibility in mind. Text (other than marginalia) is shown at a minimum of { color: #767676 } which I’ve been told is as light as you should you go.

This is what I mean by marginalia, which is covered under Special Effects.

I chose FOUT over FOIT when it came to my font loading strategy. The blog falls back to “Lucida” using Windows & Mac native equivalents until “Open Sans” arrives. Yes, the flash of the font rewrite(s) are … disappointing. But it’s the best compromise for readers with limited bandwidth.

Also, :punch: .

Syntax Highlighting

I reckon my code should look like code.

# and I reckon it should look good in a box, too.
#   to emphasize my good advice
#   like,
rm -rf /

<!-- TODO:  no matter how I represent it -->

With Jekyll, the Markdown ``` renders to a Rouge / Pygments Element heirarchy, whereas the {% highlight %} tag renders to a different one. Maybe I’ve mis-conifgured Jekyll. Who really knows at this point. But I also embed my own Gists, so either way, I have multiple fish to fry.

The green-and-purple statement of the perldoc theme is perfect for my palette of greens. The jwarby/jekyll-pygments-themes Repo houses a good variety of pre-built CSS files from the Pygments gallery.

Unfortunately, perldoc isn’t offered out-of-the-box from the lonekorean/gist-syntax-themes Repo. So I had to :smoking: roll my own CSS Selector color mapping.

I used the monokai Gist, Jekyll and Pygments styles as comparative references. This Issue thread on GitHub-Dark provided a good reference for the Gist selectors. Then it was just a matter of crushing it.

Which I did. I crushed it. And if I didn’t suspect that, at it’s heart, my perldoc implementation is kinda :poop: , I’d contribute it back to the Community. But … it kinda is.

Build Tools

You can’t call a site “modern” these days if it doesn’t have a JavaScript build chain. The current hype du jour was webpack, but I went with gulp v4. Their formal introduction of gulp.serial and gulp.parallel sealed the deal for me. If you’re still using v3 or below, here’s a nice upgrade guide.

If you discover that 4.0 has been merged to master, please let me know so I can update the link. They’d kept it off on a non-breaking branch for a looong time.

These plugins are the power behind the throne:

Deployment-wise, I know it’s all the rage to host static content from Github Pages or S3, but I’ve already got nginx running on an EC2 instance built from Chef, so I’ll stick with what works.

Special Effects

I believe that there is a fine line between enhancement and gaudiness. So fine a line, in fact, that I drew, erased, and redrew that line at least a dozen times during this project.

I’m pretty sure I mentioned the whole Perfectionist thing within the first 3 sentences.

Every blog needs an on-scroll effect these days. Eschewing the aesthetics of the famous locking static nav, or the ever-popular bouncing profile pic, I instead mounted an opacity gradient over the sidebar logo. This helps it match the color intensity of the massive “watermark” logo. When the watermark and gradient scroll out of frame, the sidebar logo gets its color mojo back.

Oh, I should mention … some of these effects, like that one :point_up: , can only be seen in a “widescreen” layout, as covered under Markup.

Sorry, Tennessee.

:point_left: That is not an example of “marginalia”.

That is a <blockquote />.

Sorry, Tennessee.

Still, I needed a good excuse to use stutrek/scrollMonitor, so under the sidebar logo you’ll find a progress lozenge. It renders passively at 20fps to avoid introducing any jank.

My FOUT strategy – as discussed at length under Font – was implemented with bramstein/fontfaceobserver and a modecum of marker classes.

For social sharing buttons, I went with absolutely fucking nothing.

Oh, but I really do like the way that Github and other sites have passive bookmark indicators on all their <h* /> elements. So I went and did that client-side with a little DOM jiggling.

I was so delighted by this article on interactive marginalia that I chose to experiment with faded-out copy in the the right-hand gutter. It’s an attempt to reduce distraction; the “interactive” part is the full reveal on :hover or :focus. Semantically-speaking, it’s treated as <small />.

But enough about all that. Let’s talk about the detonator.

It takes on a Lynchian flicker once the heading scrolls out of view. You can make it stop that! with a hover. Clicking on it will produce a UX which clearly violates WCAG 2.0 Guidelines 2.3: Do not design content in a way that is known to cause seizures.

It was inspired by the ‘release of the Hypnodrones’ from Universal Paperclips, but is much much freakier, more like the love-child of Electric Soldier Porygon and Twin Peaks Season 3 Episode 8.

Thank you StackOverflow for describing how to dynamically remove a stylesheet. All that remains is an HTML Document in all of its naked glory. The background-color and font-family are added cheats to evoke those sweet, sweet memories of Netscape Navigator 3.01 Gold.

And, let me just say right now that mroderick/PubSubJS really ties the room together. All the other effects obediently shut down post-detonation.

If you’re curious, you can always view-source the code. I even left you the comments, kids :relieved: .

 

And now … finally, as promised waaaaay earlier in this post … here is recognition for the Creative Commons artworks used on this site.

Attributions

Many of the icons used on this site fall under the Creative Commons BY 3.0 license. For example, article meta-information is denoted by

Clock by Alfa Design
Newspaper by unlimicon
Business Card by Nanda Ririz
Tag by artworkbean
Bucket by Austin Condiff

There’s an occasional left gutter accent

Link from IcoMoon-Free
Documents by Kidiladon
Check by Austin Condiff
Exclamation by Francisco Garcia Gallegos
Lotus by Nick Bluth
Dagger by Sumana Chamrunworakiat

And the ever-present <footer />

Book by Mike Rowe
RSS by Javi Ayala
Github from IcoMoon-Free
Twitter from IcoMoon-Free
Envelope by Xela Ub

Plus, for effect,

The nature of which is covered under … you guessed it … Special Effects.

Radiation by Shastry
Radiation by Shastry
Radiation by Shastry
Nuclear by Shastry
Mushroom Cloud by icon 54
Explosion by Anbileru Adaleru
Ash Cloud by Sarah JOY
Atom by Gregor Cresnar
Electric by Seymur Allahyarli
Fireworks by James Keuning

The emojis sprinkled throughout these pages are provided by the jemoji Plugin, as cross-referenced by the Emoji cheat sheet for GitHub :ok_hand: and a great listing @ onmyway133/emoji :thumbsup: .

But when it comes down to brass tacks, who doesn’t just ❤❤❤ kicking back with some Character Entity References, right?