Minima Styling Mayhem 28 Apr 2020

I thought I was being so cool. “Why use Medium?”, I thought. “I’m smart. I’m independently minded. I should host my own blog on Github using Jekyll.” The default setup truly is a breeze:

  ~$ gem install bundler jekyll

  ~$ jekyll new my-awesome-site

  ~$ cd my-awesome-site

  ~$ bundle exec jekyll serve

And voilà! you’ll have your new website running on localhost:4000 and if you push it up to a repo called your_github_username.github.io it’ll immediately go live at that address. In keeping with other ruby-based frameworks such as Ruby on Rails, there seems to be a “convention over configuration” approach in Jekyll, especially when using it as a ruby gem in conjunction with Github Pages. Here are a few things I’ve learned:

Github Pages

Jekyll loves themes. There are many sites dedicated to both free and paid themes, and many of them look amazing! However Github Pages does not support all of them. In fact, Pages only supports 13 of them natively. The default is minima 2.5. (A quick aside: Minima 2.5 != Minima 3.0). Themes were pain-point number one for me. Don’t find an awesome theme, spin up your local Jekyll server, make it look awesome, and then push it to Github, because an incompatible theme will result in your site being unrenderable. Luckily, Github will notify you via email if you’re using a theme they don’t support, but it’s a real heartbreaker after a few hours making your site exactly what you want on your local machine.

After struggling to navigate re-theming my blog, I decided to just customize my site as it was. I didn’t find much consistent documentation about how to customize my particular setup (jekyll minima gem version 2.5 free github pages), so I set to hacking.

Jekyll Conventions

Customizing Jekyll themes can be pretty fun, once you understand the file structure and naming conventions:

• Jekyll includes a file called _config.yml in the root project directory. This file takes in a lot of boilerplate content such as site title and description, social media links, and jekyll plugins such as rss feed creation, emoji integration, and many more.

• Jekyll does not require you to create any HTML. All site content is created via markdown, and Jekyll magic renders it as HTML pages with consistent mobile-and-desktop-friendly CSS. Simple blocks at the top of the file specify general attributes:

    ---
    layout: post
    comments: true
    title:  "Minima Styling Mayhem"
    date:   2020-04-28 16:15:22 -0700
    categories: github pages minima
    ---

• Jekyll allows you to replace css stlying, partial layouts, and entire page layouts, as long as the file structure remains the same. It can be counterintuitive, but here’s what I’ve learned so far:

assets

The assets folder holds styling information. Here is minima 2.5 default styling. It uses Sass files to style the pages generated by the theme gem. In order to override defaults, your project must create the same file in the same folder; e.g.: /my-awesome-site/assets/main.scss.

_layouts

_layouts contains entire-page HTML templates. To override a theme default, the title and extension of the custom page must match the original. Layouts can include raw HTML or special variables wrapped like so: {{ content }}. Site content can be rendered differently by simply specifying the layout via the layout: flag at the top of the page markdown.

_includes

_includes stores information for partials. I created custom includes to change my footer and to allow for comments on posts via Disqus. They are also HTML files, but they are only rendered if called via a tag in a layout: {% include my_custom_footer.html %}.

Customizing Minima 2.5

As I mentioned earlier, the gem version of minima is not the most recent version of the theme, which is currently at 3.0. Minima 3.0 brings some pretty big changes to the file structure and the ability to skin your site in different color palettes. For Minima 2.5, I had to do things manually.

1. Grab the assets/main.scss file from the github repo and create the same assets folder in your project’s root directory. Put main.scss inside.

2. Fire up your local jekyll instance by running bundle exec jekyll serve. This will generate content in a folder labelled _site in your root directory. Copy the contents of _site/assets/main.css into assets/main.scss.

3. Remove or comment out @import minima, otherwise any customizations you do will be overwritten by the gem defaults.

4. Customize away! So far all the edits I’ve done have persisted and render just fine on Github Pages.

Hopefully this post helps unwind some of the vagaries of Jekyll and Github Pages. Happy theming!