This is an old post. Information here may be out-dated, or the post may reflect opinions or beliefs I no longer share.
A note on quality
This is a “draft” post. If you’re looking for an explanation of what a draft post is doing on a published site, you can find one here.
In short, this post most likely does not meet my high standards — at times, even baseline. It may not be complete, have spelling errors, etc. I have published it because I think in some way, as insignificant as it could be, you might find it resourceful.
Recently, in September 2019, I published a lot of improvements to my site. Key among them:
- Header and footer areas are now visually distinct from the content of the site - using subtle backgrounds and margins.
- Blog posts have an auto generated Table of Contents so I don’t have to worry about making an
Overviewsection manually, as I had done on a couple of my earlier posts.
- Using Jekyll’s
_datafiles to output the navigation in the header, and the socials in the footer.
- Writing my own asset pipeline using Gulp - one that I understand completely, suits my needs exactly, and can tinker with relative ease as I have the mental model with me.
- This also brought my up to speed with some major changes in
- Struggling with some strange behavior in live reloading also brought me to understanding globs a little bit better in Node.
- This also brought my up to speed with some major changes in
So far, I talked about some technical aspects and improvements.
What I really want to share are my thought process behind some decisions I made during the redesign process. My main motive was not to succumb to my desire to start from scratch and create a perfect, model site — but to retain whatever I had and make improvements in areas I felt problems arise over the last few months. Prior to writing my own
gulpfile, I was using frasco. It’s an excellent starter kit, but I began to have issues with Netlify deploys and I had spent enough time trying to fix the build scripts to little resolve.
Unfortunately, I do not use any analytics on my site as I try to steer clear of Google whenever I can, and I have not (yet) found a free/freemium replacement just as easy to use. I share the lack of analytics bit with you to tell you that my decisions are not based in data.
User experience aspects
Removing blog excerpts from a list page
A list page would be the blog index, an archive page for a tag, category, or author.
Removing blog excerpts demands that the title of the blog posts be as succint yet descriptive and clear as possible, at first read.
Excerpts bring along with them a maintenance headache. The list pages are now far easier to scan through. Coupled with fast page-loads, I personally do not see this as a negative change.
Clearly separating out the header and footer from the main content
I do not think I needed to do this for the header/footer areas themselves, as they were quite lightweight in terms of content.
What this brings to the table is more emphasis on the content area at first-glance –- and that’s great. Gentle reminder: not a data based decision!
Painlessly generating a Table of Content for my articles
For the Table of Content on articles/posts, I wanted something that would in no way affect my Markdown files themselves, be easy to use, and be configurable enough to ignore headings beyond a certain heading level.
The idea was to…
- never touch the plugin, ever, after an initial configuration.
- keep my markdown files as spec-compliant as possible, and not fall prey to flavour specific syntax.
Allejo’s jekyll-toc was perfect for this.
Embracing upcoming CSS standards
One of my goals while writing the asset pipeline was to try and not resort to SCSS. It’s something I am far too comfortable in — to the point where I faced great internal reluctance to even try and make a switch. Since
autoprefixer was a guaranteed inclusion, it seemed like a great opportunity to refrain from resorting to my old friend for a simple project such as this one. Believe me, I had my moments of doubt, but I’m happy to have stuck to a sass-less :wink: build.
An additional benefit from using PostCSS plugins such as
postcss-import is getting used to syntax that’s up and coming in CSS. During my reading, apologies for the lack of a definite reference, someone mentioned they had been described PostCSS as the “Babel of CSS”- writing next generation CSS today. Very apt! :)
A third benefit is you only use as many plugins as you need to, keeping your build lighter and flexible.
And lastly, opting for PostCSS also allowed me to add
purgecss. TailwindCSS can get very, very heavy with the thousands of utility classes - something the official docs do mention and a purge for production builds just makes sense. Combined with
cssnano (a minifier for PostCSS) and the Netlify server serving files gzipped, a development build weighing 918.6KB has come down to just 11.91KB purged and minified, and 3.44KB gzipped — Incredibly light!
Extracting components for TailwindCSS
Using a framework like TailwindCSS means you are entirely reliant on utility classes.
A good practice (necessity) while using TailwindCSS is being able to move code into partials/includes/components.
The beautiful part of this framework is it does not dictate any specific templating language or framework the partials have to be written in. Use what works! Since I’m on Jekyll at the moment, I’m just using
Liquid includes and passing parameters when needed. You can use Vue, React, Handlebars and more!
include components/button.html link="https://github.com" text="Github"
In most scenarios, this keeps things simple. Unfortunately, it does get a bit verbose in other use-cases.
I do wish to move to
@eleventy/11ty once it matures some more - I’m not as proficient in Ruby as I would like, and maintaining a
Gemfile and a
11ty would then also allow me to change my template language as well as easily write anything I need to without scouring the internet hoping a Ruby-Liquid-Jekyll enthusiast has written something that can be dropped-in and used quickly –- and that it works for my purpose.
Some measures and rules I’ve made to make sure my blog and site as long as possible.
Use Markdown. If you don’t know how to write in Markdown, it’s easy. Learn.
Using standard markdown as much as possible has served me very well. I’ve been writing almost all of my blog posts in Markdown for about 4 years now - and I’ve rarely had issues hopping between tools. A lot of my personal notes are in Markdown too!
Not tinkering with URLs
I’ve sporadically been changing URLs/permalinks for a while now. That in itself is not a problem, but I almost never followed it up with configuring 301 HTTP redirects.
In short, anyone landing on the old URLs would be out of luck!
Two measures here:
- Don’t mess with URLs. Make a system, stick with it. This cuts the problem at its root. However, not always possible.
- When you do need to tinker with URLs, study the changes and configure redirects appropriately and make it a crucial part of your next deploy.
No frameworks, libraries. This is a static site with just a few pages and a blog. It does not need React.
Author-friendly blog –- just in case!
I have added a simple author functionality using a data file and an include.
At the moment, everything is written by me. Should there be a need in the future, we’re ready!