Minimal-Mistakes-Jekyll - Setup and Configuration

13 minute read

I was creating this with the idea of making it easier for people to contribute to the creation of decentralized-id.com. It didn’t really work that way, but has been getting tons of trafic, which I decided to bring over to this web-work.tools domain, where I keep track of educational resources for deploying static sites, and beyond.

Some of the setup of this site may not be exactly as described here, because of that transition.

Why Minimal Mistakes?

Generally speaking, I like to use and learn know a variety of static site generators and theier themes.

However, I’ve used Minimal Mistakes to publish large websites and small web-sites. It really works. It works well. Even before you know how to use all of it’s features, its a really reliable framework.

It supports an incredible variety of functions that simply work. For building public-domain educational resources, it makes sense for me to stick with what’s tried and true. I’ve tried to find other themes that offer a comprable feature set, and it’s not easy.

Much appreciation to Michael Rose!!

Getting Started

Minimal-Mistakes Quick-Start Guide
web-work-tools/minimal-mistakes (source repository for this website)
GitHub Pages Starter Pack
mmistakes/minimal-mistakes

Pre-requisites

You must have installed Git,` and the Ruby Bundler.

I’ll also recommend using VSCode, because it’s fully integrated with git, so that you don’t have to worrying about learning git commands.

Also, I usually create a new repository on github, first. Then I clone it locally, again, avoiding the terminal. Meaning we can learn git in more depth, at our leisure.

Site Structure

Before we get started, here is a high-level view of the site-structure.

minimal-mistakes

minimal-mistakes
├── _data                      # data files for customizing the theme
|  ├── navigation.yml          # main navigation links
|  └── ui-text.yml             # text used throughout the theme's UI
├── _includes
|  ├── analytics-providers     # snippets for analytics (Google and custom)
|  ├── comments-providers      # snippets for comments
|  ├── footer                  # custom snippets to add to site footer
|  ├── head                    # custom snippets to add to site head
|  ├── feature_row             # feature row helper
|  ├── gallery                 # image gallery helper
|  ├── group-by-array          # group by array helper for archives
|  ├── nav_list                # navigation list helper
|  ├── toc                     # table of contents helper
|  └── ...
├── _layouts
|  ├── archive-taxonomy.html   # tag/category archive for Jekyll Archives plugin
|  ├── archive.html            # archive base
|  ├── categories.html         # archive listing posts grouped by category
|  ├── category.html           # archive listing posts grouped by specific category
|  ├── collection.html         # archive listing documents in a specific collection
|  ├── compress.html           # compresses HTML in pure Liquid
|  ├── default.html            # base for all other layouts
|  ├── home.html               # home page
|  ├── posts.html              # archive listing posts grouped by year
|  ├── search.html             # search page
|  ├── single.html             # single document (post/page/etc)
|  ├── tag.html                # archive listing posts grouped by specific tag
|  ├── tags.html               # archive listing posts grouped by tags
|  └── splash.html             # splash page
├── _sass                      # SCSS partials
├── assets
|  ├── css
|  |  └── main.scss            # main stylesheet, loads SCSS partials from _sass
|  ├── images                  # image assets for posts/pages/collections/etc.
|  ├── js
|  |  ├── plugins              # jQuery plugins
|  |  ├── vendor               # vendor scripts
|  |  ├── _main.js             # plugin settings and other scripts to load after jQuery
|  |  └── main.min.js          # optimized and concatenated script file loaded before </body>
├── _config.yml                # site configuration
├── Gemfile                    # gem file dependencies
├── index.html                 # paginated home page showing recent posts
└── package.json               # NPM build scripts

CSS - Stylesheets

At the moment, I’m quite CSS agnostic. One thing at a time.. However, if you wanted to add a little style to the page, the community might appreciate that.

mmistakes.github.io/minimal-mistakes/docs/stylesheets/

The theme’s assets/css/main.css file is built from several SCSS partials located in _sass/ and is structured as follows:

minimal-mistakes
├── _sass
|  └── minimal-mistakes
|     ├── vendor               # vendor SCSS partials
|     |   ├── breakpoint       # media query mixins
|     |   ├── magnific-popup   # Magnific Popup lightbox
|     |   └── susy             # Susy grid system
|     ├── _animations.scss     # animations
|     ├── _archive.scss        # archives (list, grid, feature views)
|     ├── _base.scss           # base HTML elements
|     ├── _buttons.scss        # buttons
|     ├── _footer.scss         # footer
|     ├── _masthead.scss       # masthead
|     ├── _mixins.scss         # mixins (em function, clearfix)
|     ├── _navigation.scss     # nav links (breadcrumb, priority+, toc, pagination, etc.)
|     ├── _notices.scss        # notices
|     ├── _page.scss           # pages
|     ├── _print.scss          # print styles
|     ├── _reset.scss          # reset
|     ├── _sidebar.scss        # sidebar
|     ├── _syntax.scss         # syntax highlighting
|     ├── _tables.scss         # tables
|     ├── _utilities.scss      # utility classes (text/image alignment)
|     └── _variables.scss      # theme defaults (fonts, colors, etc.)
├── assets
|  ├── css
|  |  └── main.scss            # main stylesheet, loads SCSS partials in _sass

To make basic tweaks to theme’s style Sass variables can be overridden by adding to <your_project>/assets/css/main.scss. For instance, to change the link color used throughout the theme add:

$link-color: red;

_variables.scss

There are a number of other variables, you may find by following the link. These are the variables I have changed, so far. Before messing with CSS please check the variables, to be sure you aren’t doing too much work!

Changing the Font-Size

Upgrade-friendly way of adjusting font sizes globally

So what you can do is add any overriding/new CSS after the @import minimal-mistakes;, in your case:

@import "minimal-mistakes";

html {
  font-size: 16px; // change to whatever

  @include breakpoint($medium) {
    font-size: 18px; // change to whatever
  }

  @include breakpoint($large) {
    font-size: 20px; // change to whatever
  }

  @include breakpoint($x-large) {
    font-size: 22px; // change to whatever
  }
}

Because this theme is entirely responsive, if you want to change the font-size, you should do it like so.

Minimal Mistakes Initial Setup

I clone minimal-mistakes into the same directory as whatever website I’m working on, so they are right next to eachother.

git clone https://github.com/mmistakes/minimal-mistakes.git

Then I copy over these files and directories to the folder that is linked to the github repository where I want to be able to publish it from.

According to the quickstart guide, when forking these can be safely deleted:

    .editorconfig
    .gitattributes
    .github
    .git
    /docs
    /test
    CHANGELOG.md
    minimal-mistakes-jekyll.gemspec
    README.md
    screenshot-layouts.png
    screenshot.png

I’ve moved /docs and /test to /example-site, and added .git, since we’re cloning the project, but not forking it, we won’t be keeping them linked and can also remove the .git file, and then copied everything that’s left over to my project directory, that has its own history and .git files.

I might delete some of the layouts and includes, later. test push I’m pretty sure all I need is a gem-file and _config.yml. The Gem Install means that GitHub will use a Ruby Gem Package that contains everything needed to run the website. You only need the files that you want to customize or configure somehow. For me, I usually need to change the head, and footer, as well as the social share, but I also change the home layout. It’s much easier to learn how the site works with all the files in one place.

Gemfile

The gem-file must be properly set up to build and test your changes locally. Not necessary for minor changes, but if you get very deep into working on a web-site, you’ll not want to depend on live testing every change ;)

I’m following instructions from Minimal-Mistakes Quick-Start Guide, but also I’ve figured some of this out as I go.

Change the Gemfile so it looks like so:

source 'https://rubygems.org'
gem "minimal-mistakes-jekyll"

gem "jekyll-paginate"
gem "jekyll-sitemap"
gem "jekyll-gist"
gem "jekyll-feed"
gem "jemoji"
gem "jekyll-include-cache"
gem 'html-proofer'

Every plugin listed in your _config.yml should be also listed in your gem-file, if you want it to work locally, and if your features depend on some of these plugins, then its best to put them in the gemfile as well.

Then, once saved, run the bundle command in the root directory of your project.

bundle install then bundle update then bundle exec jekyll serve

if all went well you should be looking at a screen like this:

Honestly I had to change a few things during the creation of this guide, and am not 100% it would guide you safely through a fresh install from scratch. I’m like 95% sure, but I’ll try it out soon and make sure.

In the mean-time, this is plenty to get you started learning about how things work, around here.

_config.yml

We’ll aim to keep this page updated with whatever is the most recent configuration, with notes of explanation when necessary.

minimal_mistakes_skin    : "dirt" # "air", "aqua", "contrast", "dark", "dirt", "neon", "mint", "plum", "sunrise"
                                  
# Site Settings
locale                   : "en-US"
title                    : "DIDecentral"
title_separator          : "-"
name                     : "DIDecentral"
description              : "Community operations and social syndication archive for decentralized-id.com."
url                      : "https://web-work.tools"
baseurl                  : /minimal-mistakes
repository               : web-work-tools/minimal-mistakes
teaser                   : # path of fallback teaser image, e.g. "/assets/images/500x300.png"
logo                     : https://web-work.tools/images/logo.png
masthead_title           : Walkthroughs for a Community Webpage
words_per_minute         : 200

We just got set up with comments, and will add info here soon.

# Site Author
author:
  name             : "DIDecentral"
  avatar           : /assets/images/did-square.png
  bio              : "Open Source, Public Domain, Educational Initiative"
  location         : "Curating the Web"
  links:
    - label: "Email"
      icon: "fas fa-fw fa-envelope-square"
      url: mailto:identitydecentralized@gmail.com
    - label: "Website"
      icon: "fas fa-fw fa-link"
      url: "https://decentralized-id.com"
    - label: "Twitter"
      icon: "fab fa-fw fa-twitter-square"
      url: "https://twitter.com/decentralizeid"
    - label: "GitHub"
      icon: "fab fa-fw fa-github"
      url: "https://github.com/decentralized-id"

# Site Footer
footer:
  links:
    - label: "Email"
      icon: "fas fa-fw fa-envelope-square"
      url: mailto:identitydecentralized@gmail.com
    - label: "Website"
      icon: "fas fa-fw fa-link"
      url: "https://decentralized-id.com"
    - label: "Twitter"
      icon: "fab fa-fw fa-twitter-square"
      url: "https://twitter.com/decentralizeid"
    - label: "GitHub"
      icon: "fab fa-fw fa-github"
      url: "https://github.com/decentralized-id"

I just went to fontawesome.com and it’s pretty simple to try and match above formula without thinking too deeply on the matter.

_config.yml - Permalink Defaults

The permalink default defines permalinks, in the case that they are not defined within a post.

# Outputting
permalink: /:categories/:slug/  # https://jekyllrb.com/docs/permalinks/
paginate: 5 # amount of posts to show
paginate_path: /page:num/
timezone: # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

category_archive:
  type: liquid
  path: /categories/
tag_archive:
  type: liquid
  path: /tags/

_config.yml - Frontmatter Defaults

You can over-ride these defaults on a page-by-page basis.

# Defaults
defaults:
  # _posts
  - scope:
      path: "_posts"
      type: posts
    values:
      layout: single
      author_profile: false
      read_time: true
      comments: # true
      share: true
      related: true
      header:
       image: /assets/images/didecentral.png #the image at the top of the page
       og_image: /assets/images/did-og.png #the image preview on twitter, discord, etc.
      sidebar:
        nav: "didnav"
  # _pages
      toc: true
  - scope:
      path: "_pages"
      type: pages
    values:
      layout: single
      author_profile: false
      read_time: true
      comments: # true
      share: true
      related: true
      header:
       image: /assets/images/didecentral.png
       og_image: /assets/images/did-og.png
      sidebar:
        nav: "didnav"
      toc: true
  # _application
  - scope:
      path: "_application"
      type: application
    values:
      layout: single
      share: true
      related: true
      sidebar:
        title: "DID ⧉ Nav"
        nav: "didnav"
      classes: wide
      disco: true
      header:
       image: /assets/images/did-header.png
       og_image: /assets/images/did-og.png
  # _blockchain
  - scope:
      path: "_blockchain"
      type: blockchain
    values:
      layout: single
      share: true
      related: true
      disco: true
      sidebar:
        nav: "didnav"
      classes: wide
      header:
       image: /assets/images/did-header.png
       og_image: /assets/images/did-og.png
    # _multi-media
  - scope:
      path: "_multi-media"
      type: "multi-media"
    values:
      layout: single
      share: true
      disco: true
      related: true
      sidebar:
        nav: "didnav"
      classes: wide
      header:
       image: /assets/images/did-header.png
       og_image: /assets/images/did-og.png
    # _organizations
  - scope:
      path: "_organizations"
      type: organizations
    values:
      layout: single
      share: true
      related: true
      disco: true
      sidebar:
        nav: "didnav"
      classes: wide
      header:
       image: /assets/images/did-header.png
       og_image: /assets/images/did-og.png
    # _private-sector
  - scope:
      path: "_private-sector"
      type: "private-sector"
    values:
      layout: single
      share: true
      related: true
      disco: true
      sidebar:
        nav: "didnav"
      classes: wide
      header:
       image: /assets/images/did-header.png
       og_image: /assets/images/did-og.png
    # _public-sector
  - scope:
      path: "_public-sector"
      type: "public-sector"
    values:
      layout: single
      share: true
      related: true
      sidebar:
        nav: "didnav"
      classes: wide
      disco: true
      header:
       image: /assets/images/did-header.png
       og_image: /assets/images/did-og.png
    # _resources
  - scope:
      path: "_resources"
      type: resources
    values:
      layout: single
      share: true
      related: true
      disco: true
      sidebar:
        nav: "didnav"
      classes: wide
      header:
       image: /assets/images/did-header.png
       og_image: /assets/images/did-og.png
    # _tech
  - scope:
      path: "_tech"
      type: tech
    values:
      layout: single
      share: true
      related: true
      disco: true
      sidebar:
        nav: "didnav"
      classes: wide
      header:
       image: /assets/images/did-header.png
       og_image: /assets/images/did-og.png

_data/navigation.yml

Then if you look up there in the front-matter defaults, you’ll see where the navigation is called as a part of the sidebar class.

# main links
main:
  - title: "Quick-Start Guide"
    url: https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/
  - title: "Web-Work.Tools"
    url: https://web-work.tools
  # - title: "About"
  #   url: https://mmistakes.github.io/minimal-mistakes/about/
  # - title: "Sample Posts"
  #   url: /year-archive/
  # - title: "Sample Collections"
  #   url: /collection-archive/
  # - title: "Sitemap"
  #   url: /sitemap/

# DID Nav

didnav:
  - title: Contributors Guides
    children:
      - title: "Minimal-Mistakes - Configuration"
        url: /website-configuration/
      - title: Discord Archive Walktrhu
        url: /discord-archive-howto/
  - title: Archives
    url: /archives/
    children:
      - title: Resources
        url: /archives/resources/
      - title: Multi-Media
        url: /archives/multi-media/
      - title: Blockchain
        url: /archives/blockchain/
      - title: Organizations
        url: /archives/organizations/
      - title: Public Sector
        url: /archives/public-sector/
      - title: Private Sector
        url: /archives/private-sector/
      - title: Tech
        url: /archives/tech/
      - title: Application
        url: /archives/application

This is the code that makes social share and donation button on each page. The Bitcoin, Tippin.me, and DOGE addresses are specific for DIDecentral, and currently under @infominer33’s control.

_includes/social-share.html

<section class="page__share">
<h2><a href="https://github.com/web-work-tools/minimal-mistakes/blob/master/{{ page.path }}" class="edit">Edit this page <i class="fa fa-pencil"></i></a></h2>
<h3>Social Share</h3>
<a href="https://twitter.com/intent/tweet?{% if site.twitter.username %}via={{ site.twitter.username | url_encode }}&{% endif %}text={{ page.title | url_encode }}%20{{ page.url | absolute_url | url_encode }}" class="btn btn--twitter" onclick="window.open(this.href, 'window', 'left=20,top=20,width=500,height=500,toolbar=1,resizable=0'); return false;" title="Share on Twitter"><i class="fab fa-fw fa-twitter" aria-hidden="true"></i><span> Twitter</span></a>
<a href="https://www.facebook.com/sharer/sharer.php?u={{ page.url | absolute_url | url_encode }}" class="btn btn--facebook" onclick="window.open(this.href, 'window', 'left=20,top=20,width=500,height=500,toolbar=1,resizable=0'); return false;" title="Share on Facebook"><i class="fab fa-fw fa-facebook" aria-hidden="true"></i><span> Facebook</span></a>
<a href="https://www.linkedin.com/shareArticle?mini=true&url={{ page.url | absolute_url | url_encode }}" class="btn btn--linkedin" onclick="window.open(this.href, 'window', 'left=20,top=20,width=500,height=500,toolbar=1,resizable=0'); return false;" title="Share on LinkedIn"><i class="fab fa-fw fa-linkedin" aria-hidden="true"></i><span> LinkedIn</span></a>
<a href="https://www.reddit.com/submit?url={{ page.url | absolute_url | url_encode }}&title={{ page.title | url_encode }}" class="btn btn--reddit" title="Share on Reddit"><i class="fab fa-fw fa-reddit" aria-hidden="true"></i><span> Reddit</span></a>
<h3>Tips Welcome</h3>
<table class="table table-bordered table-hover table-condensed">
  <thead>
    <tr>
      <th title="Field #1">Bitcoin</th>
      <th title="Field #2">DOGE</th>
    </tr>
    </thead>
    <tbody>
    <tr>
      <td>1D9382Y1hwF9mx8tRu8ZUVxcm2aq6yZDYR</td>
      <td>D9y38ChAZP9aZG2mAJ94VAynAG4YGSvTpp</td>
    </tr>
    <tr>
      <td><img src="https://imgur.com/j1hzcTo.png" width="150"></td>
      <td><img src="https://i.imgur.com/V3EnMAes.png" width="150"></td>
    </tr>
  </tbody>
</table>  
<!-- Beginning of tippin.me Button -->
<div id="tippin-button" data-dest="didecentral"></div>
<script src="https://tippin.me/buttons/tip.js" type="text/javascript"></script>
<!-- End of tippin.me Button -->
</section>

Reddit Button

_sass/minimal-mistakes/_buttons.scss

If you copy that part to get the reddit button included with the others, you might find that you are missing the actual button.

just head over to buttons.css :rofl: (idk why that’s so funny to me)

  /* button colors */
  $buttoncolors:
  (primary, $primary-color),
  (inverse, #fff),
  (light-outline, transparent),
  (success, $success-color),
  (warning, $warning-color),
  (danger, $danger-color),
  (info, $info-color),
  (facebook, $facebook-color),
  (twitter, $twitter-color),
  (linkedin, $linkedin-color),
  (reddit, $reddit-color);

Because the Reddit Color is already defined in _variables.scss, all you need to do is reference it here.

Author vs Authors

There are two variables that must always be considered.

Author, is for the initial or primary author. Authors is for all the people who have contributed to that document.

So if you make a new post be sure to set both in your front-matter

---
title: "Your Awesome Post"
author: "AwesomeYou"
authors: ["AwesomeYou"]
---

Then if I came and touched up your post, I would add myself to the authors:

---
title: "Your Awesome Post"
author: "AwesomeYou"
authors: ["AwesomeYou","infominer33"]
---

Every post and page should have these, but I’m used to being the only author, so that will require some work, or maybe will leave old articles alone… not sure

Authors Code

This was really crudely hacked together from the other lists in this section.

_includes/authors-list.html

<p class="page__taxonomy">
    <strong><i class="fas fa-fw fa-users" aria-hidden="true"></i> Authors:</strong>
    {% assign authorCount = page.authors | size %}
    {% if authorCount == 0 %}
        No author
    {% elsif authorCount == 1 %}
        {{ page.authors | first }}
    {% else %}
        {% for author in page.authors %}
            {% if forloop.first %}
            <a href="{{ author.url }}" rel="author">{{ author }}</a>
            {% elsif forloop.last %}
                and <a href="{{ author.url }}" rel="author">{{ author }}</a>
            {% else %}
                , <a href="{{ author.url }}" rel="author">{{ author }}</a>
            {% endif %}
        {% endfor %}
    {% endif %}
</p>

/_includes/page__taxonomy.html

Also, I added this line to the page taxonomy:

{% if page.authors %}
  {% include authors-list.html %}
{% endif %}

To be continued….

There are a number of tweaks that I make to minimal-mistakes sites. All will be explained :D

Reach out in the comments if you have any questions!

Edit this page

Social Share

Twitter Facebook LinkedIn Reddit

Tips Welcome

Bitcoin	DOGE
1D9382Y1hwF9mx8tRu8ZUVxcm2aq6yZDYR	D9y38ChAZP9aZG2mAJ94VAynAG4YGSvTpp