Caution!

This is an old post. Information here may be out-dated, or the post may re­flect opin­ions or be­liefs I no longer share.

A note on qual­ity

This is a draft” post. If you’re look­ing for an ex­pla­na­tion of what a draft post is do­ing on a pub­lished site, you can find one here.

In short, this post most likely does not meet my high stan­dards — at times, even base­line. It may not be com­plete, have spelling er­rors, etc. I have pub­lished it be­cause I think in some way, as in­signif­i­cant as it could be, you might find it re­source­ful.

Recently, in September 2019, I pub­lished a lot of im­prove­ments to my site. Key among them:

  • Header and footer ar­eas are now vi­su­ally dis­tinct from the con­tent of the site - us­ing sub­tle back­grounds and mar­gins.
  • Blog posts have an auto gen­er­ated Table of Contents so I don’t have to worry about mak­ing an Overview sec­tion man­u­ally, as I had done on a cou­ple of my ear­lier posts.
  • Using Jekyll’s _data files to out­put the nav­i­ga­tion in the header, and the so­cials in the footer.
  • Writing my own as­set pipeline us­ing Gulp - one that I un­der­stand com­pletely, suits my needs ex­actly, and can tin­ker with rel­a­tive ease as I have the men­tal model with me.
    • This also brought my up to speed with some ma­jor changes in Gulp 4.
    • Struggling with some strange be­hav­ior in live re­load­ing also brought me to un­der­stand­ing globs a lit­tle bit bet­ter in Node.

So far, I talked about some tech­ni­cal as­pects and im­prove­ments.

What I re­ally want to share are my thought process be­hind some de­ci­sions I made dur­ing the re­design process. My main mo­tive was not to suc­cumb to my de­sire to start from scratch and cre­ate a per­fect, model site — but to re­tain what­ever I had and make im­prove­ments in ar­eas I felt prob­lems arise over the last few months. Prior to writ­ing my own gulpfile, I was us­ing frasco. It’s an ex­cel­lent starter kit, but I be­gan to have is­sues with Netlify de­ploys and I had spent enough time try­ing to fix the build scripts to lit­tle re­solve.

Unfortunately, I do not use any an­a­lyt­ics on my site as I try to steer clear of Google when­ever I can, and I have not (yet) found a free/​freemium re­place­ment just as easy to use. I share the lack of an­a­lyt­ics bit with you to tell you that my de­ci­sions are not based in data.

User ex­pe­ri­ence as­pects

Removing blog ex­cerpts from a list page

A list page would be the blog in­dex, an archive page for a tag, cat­e­gory, or au­thor.

Removing blog ex­cerpts de­mands that the ti­tle of the blog posts be as suc­cint yet de­scrip­tive and clear as pos­si­ble, at first read.

Excerpts bring along with them a main­te­nance headache. The list pages are now far eas­ier to scan through. Coupled with fast page-loads, I per­son­ally do not see this as a neg­a­tive change.

Clearly sep­a­rat­ing out the header and footer from the main con­tent

I do not think I needed to do this for the header/​footer ar­eas them­selves, as they were quite light­weight in terms of con­tent.

What this brings to the table is more em­pha­sis on the con­tent area at first-glance –- and that’s great. Gentle re­minder: not a data based de­ci­sion!

Painlessly gen­er­at­ing a Table of Content for my ar­ti­cles

For the Table of Content on ar­ti­cles/​posts, I wanted some­thing that would in no way af­fect my Markdown files them­selves, be easy to use, and be con­fig­urable enough to ig­nore head­ings be­yond a cer­tain head­ing level.

The idea was to…

  • never touch the plu­gin, ever, af­ter an ini­tial con­fig­u­ra­tion.
  • keep my mark­down files as spec-com­pli­ant as pos­si­ble, and not fall prey to flavour spe­cific syn­tax.

Allejo’s jekyll-toc was per­fect for this.

Techincal as­pects

Embracing up­com­ing CSS stan­dards

One of my goals while writ­ing the as­set pipeline was to try and not re­sort to SCSS. It’s some­thing I am far too com­fort­able in — to the point where I faced great in­ter­nal re­luc­tance to even try and make a switch. Since autoprefixer was a guar­an­teed in­clu­sion, it seemed like a great op­por­tu­nity to re­frain from re­sort­ing to my old friend for a sim­ple pro­ject such as this one. Believe me, I had my mo­ments of doubt, but I’m happy to have stuck to a sass-less :wink: build.

An ad­di­tional ben­e­fit from us­ing PostCSS plu­g­ins such as postcss-nesting and postcss-import is get­ting used to syn­tax that’s up and com­ing in CSS. During my read­ing, apolo­gies for the lack of a def­i­nite ref­er­ence, some­one men­tioned they had been de­scribed PostCSS as the Babel of CSS- writ­ing next gen­er­a­tion CSS to­day. Very apt! :)

A third ben­e­fit is you only use as many plu­g­ins as you need to, keep­ing your build lighter and flex­i­ble.

And lastly, opt­ing for PostCSS also al­lowed me to add purgecss. TailwindCSS can get very, very heavy with the thou­sands of util­ity classes - some­thing the of­fi­cial docs do men­tion and a purge for pro­duc­tion builds just makes sense. Combined with cssnano (a mini­fier for PostCSS) and the Netlify server serv­ing files gzipped, a de­vel­op­ment build weigh­ing 918.6KB has come down to just 11.91KB purged and mini­fied, and 3.44KB gzipped — Incredibly light!

Extracting com­po­nents for TailwindCSS

Using a frame­work like TailwindCSS means you are en­tirely re­liant on util­ity classes.

A good prac­tice (necessity) while us­ing TailwindCSS is be­ing able to move code into par­tials/​in­cludes/​com­po­nents.

The beau­ti­ful part of this frame­work is it does not dic­tate any spe­cific tem­plat­ing lan­guage or frame­work the par­tials have to be writ­ten in. Use what works! Since I’m on Jekyll at the mo­ment, I’m just us­ing Liquid in­cludes and pass­ing pa­ra­me­ters when needed. You can use Vue, React, Handlebars and more!

For ex­am­ple:

include components/button.html link="https://github.com" text="Github"

In most sce­nar­ios, this keeps things sim­ple. Unfortunately, it does get a bit ver­bose in other use-cases.

I do wish to move to @eleventy/11ty once it ma­tures some more - I’m not as pro­fi­cient in Ruby as I would like, and main­tain­ing a Gemfile and a package.json does not sit well with me. With every­thing in JavaScript, it’ll be happy days.

Moving to 11ty would then also al­low me to change my tem­plate lan­guage as well as eas­ily write any­thing I need to with­out scour­ing the in­ter­net hop­ing a Ruby-Liquid-Jekyll en­thu­si­ast has writ­ten some­thing that can be dropped-in and used quickly –- and that it works for my pur­pose.

Longevity con­cerns

Some mea­sures and rules I’ve made to make sure my blog and site as long as pos­si­ble.

Markdown

Use Markdown. If you don’t know how to write in Markdown, it’s easy. Learn.

Using stan­dard mark­down as much as pos­si­ble has served me very well. I’ve been writ­ing al­most all of my blog posts in Markdown for about 4 years now - and I’ve rarely had is­sues hop­ping be­tween tools. A lot of my per­sonal notes are in Markdown too!

Not tin­ker­ing with URLs

I’ve spo­rad­i­cally been chang­ing URLs/permalinks for a while now. That in it­self is not a prob­lem, but I al­most never fol­lowed it up with con­fig­ur­ing 301 HTTP redi­rects.

In short, any­one land­ing on the old URLs would be out of luck!

Two mea­sures here:

  • Don’t mess with URLs. Make a sys­tem, stick with it. This cuts the prob­lem at its root. However, not al­ways pos­si­ble.
  • When you do need to tin­ker with URLs, study the changes and con­fig­ure redi­rects ap­pro­pri­ately and make it a cru­cial part of your next de­ploy.

Limiting JavaScript

On the client-side, I wanted to limit the amount of JavaScript I used. At the mo­ment, I have just two func­tions, writ­ten in JavaScript ES6. I don’t see this chang­ing.

No frame­works, li­braries. This is a sta­tic site with just a few pages and a blog. It does not need React.

Author-friendly blog –- just in case!

I have added a sim­ple au­thor func­tion­al­ity us­ing a data file and an in­clude.

At the mo­ment, every­thing is writ­ten by me. Should there be a need in the fu­ture, we’re ready!