Nithiya Streethran

Nithiya Streethran

Environmental research and random stuff

This website uses the Minimal Mistakes theme. This theme is highly configurable, so I modified it to my liking and documented my changes here. 😄

To serve this site locally:

  1. Install Ruby.

  2. Clone this repository.

    Option 1 - SSH:

    git clone git@gitlab.com:nithiya/nithiya.gitlab.io.git

    Option 2 - HTTPS:

    git clone https://gitlab.com/nithiya/nithiya.gitlab.io.git

  3. Navigate to the cloned directory and install all requirements:

    cd nithiya.gitlab.io
gem install bundler
bundle install

  4. Serve the site:

    bundle exec jekyll serve

  5. View the site at http://localhost:4000.

Note
The following configurations work best with v4.24.0 of the Minimal Mistakes theme. If you get errors while trying to bundle install, some prerequisite libraries, such as make may be missing. Check the error messages and install the missing libraries to fix this issue. To update gems, use bundle update.

Theme configurations

Firstly, I configured the theme and skin in _config.yml:

theme: minimal-mistakes-jekyll
minimal_mistakes_skin: dark

I also configured the locale and date format:

locale: en-GB
date_format: "%-d %B %Y"

Fonts

I’m self-hosting fonts used on this site.

I configured the following fonts and set the caption font family in assets/css/main.scss:

$sans-serif: "FiraGO", -apple-system, BlinkMacSystemFont, "Roboto",
  "Segoe UI", "Helvetica Neue", "Lucida Grande", Arial, sans-serif !default;
$monospace: "Fira Code", Monaco, Consolas, "Lucida Console",
  monospace !default;
$caption-font-family: $sans-serif !default;

Info
The fonts I’m using are: FiraGO v1.001 (body — regular, italic, bold, and bold italic), Fira Code v5.2 (monospace — regular and bold), and Homemade Apple (site title).

For use on this website, a subset of the font styles were created and converted into WOFF2 format from TTF using fontTools. fontTools is a Python package which requires Brotli to convert fonts to WOFF2. The requirements are installed using pip:

python -m pip install fonttools brotli  # using Linux
py -m pip install fonttools brotli  # using Windows

The generated files can be found in assets/fonts. The font faces were then specified in assets/css/main.scss. For example:

@font-face {
  font-family: "FiraGO";
  src: url("../fonts/FiraGO/FiraGO-Italic.woff2") format("woff2");
  font-weight: 400;
  font-style: italic;
}

I also set the site title font as follows:

.site-title {
  font-family: "Homemade Apple", cursive;
  font-weight: normal;
}

The following commands, for example, were used to generate the WOFF2 font files from TTFs of Fira Code Regular and Homemade Apple; the required glyphs are specified using Unicode characters and/or text1:

pyftsubset FiraCode-Regular.ttf --unicodes=U+0020-007E --flavor=woff2 --output-file=FiraCode-Regular.woff2
pyftsubset HomemadeApple-Regular.ttf --text="Nithiya Streethran" --flavor=woff2 --output-file=HomemadeApple-Regular.woff2

To italicise comments in code blocks, I added the following to assets/css/main.scss:

.highlight {
  .c, .c1 {
      font-style: italic;
  }
}

Font Awesome icons

I’m also self-hosting the Font Awesome (v5.15.4) icon files2. They can be found in assets/fonts/FontAwesome (font files) and _sass/fontawesome (Sass style sheets). I only used the WOFF2 web font files, so I modified the Sass style sheets accordingly to remove links to other font files. For example, in _sass/fontawesome/solid.scss, I changed the @font-face source:

@font-face {
  font-family: 'Font Awesome 5 Free';
  font-style: normal;
  font-weight: 900;
  font-display: $fa-font-display;
  src: url('#{$fa-font-path}/fa-solid-900.woff2') format('woff2');
}

I also redefined the $fa-font-path in line 4 of _sass/fontawesome/_variables.scss to point to the correct font file directory:

$fa-font-path:         "../fonts/FontAwesome" !default;

In assets/css/main.scss, I imported the Font Awesome Sass style sheets after importing the Minimal Mistakes theme:

@import "fontawesome/fontawesome.scss";  // Font Awesome
@import "fontawesome/solid.scss";
@import "fontawesome/brands.scss";
@import "fontawesome/regular.scss";

I then removed the Font Awesome stylesheet CDN link from _includes/head.html (line 18-19).

To add Font Awesome icons to Markdown files, I created the helper _includes/fontawesome, which contains the following:

<i class="{{ include.class }}" aria-hidden="true"></i>

To display an icon, I simply add the following, replacing fas fa-fw fa-envelope with the icon’s class:

{% include fontawesome class="fas fa-fw fa-envelope" %}

In _includes/footer.html, I changed some lines so fixed width Font Awesome icons are used:

  • line 10:

              <li><a href="{{ link.url }}" rel="nofollow noopener noreferrer"><i class="{{ link.icon | default: 'fas fa-fw fa-link' }}" aria-hidden="true"></i> {{ link.label }}</a></li>

  • line 16:

          <li><a href="{% if site.atom_feed.path %}{{ site.atom_feed.path }}{% else %}{{ '/feed.xml' | relative_url }}{% endif %}"><i class="fas fa-fw fa-rss" aria-hidden="true"></i> {{ site.data.ui-text[site.locale].feed_label | default: "Feed" }}</a></li>

I also added custom copyright information in line 21:

<div class="page__footer-copyright">
  &copy; {{ site.time | date: '%Y' }} {{ site.name | default: site.title }}. {{ site.data.ui-text[site.locale].powered_by | default: "Powered by" }} <a href="https://jekyllrb.com" rel="nofollow">Jekyll</a> &amp; <a href="https://mademistakes.com/work/jekyll-themes/minimal-mistakes/" rel="nofollow">Minimal Mistakes</a>.
  <br/>
  <strong><i class="fab fa-creative-commons fa-lg" aria-hidden="true"></i> <i class="fab fa-creative-commons-by fa-lg" aria-hidden="true"></i></strong> Except where otherwise noted, content on this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International (CC-BY-4.0) License</a>.
</div>

Colours

In assets/css/main.scss, I used the Woodland base16 colour scheme to override the dark skin’s default colours:

$base00: #231e18 !default;
$base01: #302b25 !default;
$base02: #48413a !default;
$base03: #9d8b70 !default;
$base04: #b4a490 !default;
$base05: #cabcb1 !default;
$base06: #d7c8bc !default;
$base07: #e4d4c8 !default;
$base08: #d35c5c !default;
$base09: #ca7f32 !default;
$base0a: #e0ac16 !default;
$base0b: #b7ba53 !default;
$base0c: #6eb958 !default;
$base0d: #88a4d3 !default;
$base0e: #bb90e2 !default;
$base0f: #b49368 !default;

I then assigned these colours:

$primary-color: $base0b !default;
$link-color: $base0c !default;
$background-color: $base01 !default;
$warning-color: $base0a !default;
$info-color: $base0d !default;
$success-color: $base0c !default;
$danger-color: $base08 !default;

I then made a minor fix to the colour of the active link hover in the table of contents, so it stands out from the background. I added the following to assets/css/main.scss:

.toc .active a:hover {
  color: inherit;
}

Notices

To change the appearance of notices, I added the following to assets/css/main.scss:

@mixin notice($notice-color) {
  color: inherit;
  background-color: $notice-color;
  a {
    color: inherit;
  };
  code {
    background-color: mix($background-color, $notice-color, 25%);
  };
}

.notice {
  @include notice($base0f);
}

.notice--primary {
  @include notice($primary-color);
}

.notice--info {
  @include notice($info-color);
}

.notice--warning {
  @include notice($warning-color);
}

.notice--success {
  @include notice($success-color);
}

.notice--danger {
  @include notice($danger-color);
}

Info
See Minimal Mistakes’ documentation for more information about utility classes, such as notices, helpers, and stylesheets.

Pages

I created _pages/sitemap.html based on some of the Minimal Mistakes archive pages:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

---
title: Sitemap
layout: archive
permalink: /sitemap/
entries_layout: grid
---

A list of all the posts and pages found on this site. For you robots out there, there is an <a href="{{ "sitemap.xml" | relative_url }}">XML version</a> available for digesting as well.

<!-- Get list of pages, excluding ones without a title -->
{%- capture site_pages -%}
  {%- for post in site.pages -%}
    {%- if post.title -%}
      {{- post | first -}}
      {%- unless forloop.last -%}
        ,
      {%- endunless -%}
    {%- endif -%}
  {%- endfor -%}
{%- endcapture -%}
{%- assign pages_list = site_pages | split: ',' -%}

<!-- Display taxonomy index -->
<ul class="taxonomy__index">
  <li>
    <a href="#posts">
      <strong>Posts</strong> <span class="taxonomy__count">{{- site.posts.size -}}</span>
    </a>
  </li>
  <li>
    <a href="#pages">
      <strong>Pages</strong> <span class="taxonomy__count">{{- pages_list.size -}}</span>
    </a>
  </li>
</ul>

<!-- Assign layout of entries -->
{%- assign entries_layout = page.entries_layout | default: 'list' -%}

<!-- Display list of posts -->
<section id="posts" class="taxonomy__section">
  <h2 class="archive__subtitle">Posts</h2>
  <div class="entries-{{ entries_layout }}">
    {%- for post in site.posts -%}
      {%- include archive-single.html type=entries_layout -%}
    {%- endfor -%}
  </div>
  <a href="#page-title" class="back-to-top">{{- site.data.ui-text[site.locale].back_to_top | default: 'Back to Top' -}} &uarr;</a>
</section>

<!-- Display list of pages -->
<section id="pages" class="taxonomy__section">
  <h2 class="archive__subtitle">Pages</h2>
  <div class="entries-{{ entries_layout }}">
    {%- for post in site.pages -%}
      {%- if post.title -%}
        {%- include archive-single.html type=entries_layout -%}
      {%- endif -%}
    {%- endfor -%}
  </div>
  <a href="#page-title" class="back-to-top">{{- site.data.ui-text[site.locale].back_to_top | default: 'Back to Top' -}} &uarr;</a>
</section>

To exclude pages such as robots.txt and files in the assets directory from the list of pages, I set the Liquid code to capture only pages with a title. This was necessary as setting sitemap: false won’t work for pages hosted using GitHub or GitLab Pages3.

Info
See the Liquid and Jekyll docs for more information about the Liquid syntax.

I also commented out the paginate line in _config.yml, which allowed me to use a custom index.md file without the home layout, instead of the default index.html homepage that shows the 5 most recent posts4:

# paginate: # amount of posts to show

To add a ‘back to top’ icon which takes you to the top of the page or post5, I included the following in assets/css/main.scss:

.sidebar__top {
  position: fixed;
  bottom: .75em;
  right: .75em;
  z-index: 10;
  font-size: smaller;
  ::before {
    color: $primary-color;
  }
}

I then added the following HTML code in _includes/footer.html:

<aside class="sidebar__top" title="Back to Top">
  <a href="#site-nav"><i class="fas fa-fw fa-angle-double-up fa-2x" aria-hidden="true"></i></a>
</aside>

I’m not using breadcrumbs the intended way (i.e. by specifying the permalink for posts as /:categories/:title/). As I set the post permalink to /post/:title/, I had to make some changes to _includes/breadcrumbs.html:

  • line 1:

    {% case site.year_archive.type %}

  • line 12:

      {% assign crumb_path = site.year_archive.path %}

  • line 32:

              <span itemprop="name">{{ crumb | replace: '-', ' ' | replace: '%20', ' ' | capitalize }}</span>

Comments

I’ve set up Staticman comments on this site. Check out this post to find out how I did it.

To automatically add an external link indicator, which uses a Font Awesome icon, I configured the following in assets/css/main.scss6 7 8. This excludes the indicator in the social icons and buttons:

.page {
  a:not(.btn):not([href*="localhost:4000"]):not([href*="//nithiya.gitlab.io"]):not([href^="#"]):not([href^="/"])::after {
    content: " \f35d";
    font-family: "Font Awesome 5 Free";
    display: inline-block;
    text-rendering: auto;
    font-weight: 900;
    font-variant: normal;
    font-size: small;
    font-style: normal;
    white-space: pre;
    -webkit-font-smoothing: antialiased;
  }
}

Captions

For tables, I created a custom caption class to be used with the span tag. I added the following to assets/css/main.scss:

.caption-table {
  font-size: .75em;
  display: block;
  margin-bottom: 1.3em;
}

I then created a helper (_includes/table-caption) to display the table caption in Markdown files:

<span class="caption-table">{{ include.caption }}</span>

To display the caption, I simply add the following above a table:

{% include table-caption caption="**Table:** My caption goes here." %}

To change the gallery counter’s font family, I added the following to assets/css/main.scss:

.mfp-counter {
  font-family: $caption-font-family;
}

Other

To change the site’s favicon, I used a favicon generator and pasted the generated HTML in _includes/head.html. I dropped the generated icons in the root of the repository9. Keeping favicon.ico in the root will suppress the ERROR '/favicon.ico' not found. message10. The icon I used is emoji_u1f989 from Noto Emoji, v2017-05-18-cook-color-fix.

I am using KaTeX on this website to display mathematics. I added the following to _includes/head.html:

{% if page.math %}
  <!-- insert HTML linking to KaTeX CDN scripts and stylesheets here -->
{% endif %}

I then add math: true to the YAML metadata of posts that require math typesetting.

Footnotes

  1. subset - fontTools Documentation ↩

  2. Hosting Font Awesome Yourself - Font Awesome ↩

  3. sitemap: false doesn’t work - Issue #991 - mmistakes/minimal-mistakes - GitHub ↩

  4. Paginate - Configuration - Minimal Mistakes ↩

  5. Include “Back to top” Icon - Issue #1731 - mmistakes/minimal-mistakes - GitHub ↩

  6. Adding External Link Indicator with CSS - Waaz Solutions ↩

  7. CSS Pseudo-elements - Font Awesome ↩

  8. Add a space (“ “) after an element using :after - Stack Overflow ↩

  9. How do we change the favicon in the title bar? - Issue #585 - mmistakes/minimal-mistakes - GitHub ↩

  10. ERROR `/favicon.ico’ not found - Issue #289 - mmistakes/minimal-mistakes - GitHub ↩

Comments

Leave a comment

Your email address will not be published. Required fields are marked *.

Markdown is supported.