Mimoduo

Crank up the Torque

Day by day we rock the development world. Our pens can make us smile, strike a curious chord, and tell a charming story. Our projects can spark creativity, change an industry, and speed up our gears. It's forever so sweet to dream of all the exciting, wonderful, and surreal possibilities we come up with everyday through our work ;)

Mimogear

My entry into this dream world is none other than Mimogear! Mimogear, a simple static generator and web development boilerplate, that blends the best practices of the web into a unified web development workflow.

For those curious, no pugs were harmed in the making of Mimogear.

Ultimate Goal

The goal of Mimogear is to serve as a complete web development environment for working with the languages we know and love for those just jumping into web development and for professionals who want a sturdy foundation and a fresh start for their new site.

To accomplish this goal, Mimogear utilizes just the right mix of front end tools. Gulp.js made task runners easy to understand, Pug made html templates a piece of cake, and sass makes it easier to write the css we love.

For the New Gears

I admit, I threw a big learning cannoli at you. But it's a yummy learning cannoli ;9 Gulp, Pug, and Sass, are gonna make developing static sites blazing fast for ya.

Gulp, a node.js task runner, is no slouch and the real champion in Mimogear. Gulp does the legwork for you such as compiling assets, watching files, and even running deployments. After some initial command line setup and the execution of the gulp command, gulp will spin up in the background and work alongside you. To be more specific, gulp will:

• Compile Pug templates with json data into HTML templates,
• Compile Sass into CSS,
• Concatenate and uglify vendor and site specific javascript files,
• Optimize images,
• Compile a SVG sprite,
• Watch and live reload assets,
• And deploy to github pages, netlify, or surge (additional setup required)

Pug, a HTML template language, makes me happy. Writing HTML from scratch can be very time consuming. Pug aims to take away the verbose bracket syntax and add in a bundle of extras. This goofy little pug (capable of thermal imaging) makes for an easy way to reuse templates, include components, utilize mixins, and write HTML without much fuss. If you'd like a quick course on Pug, check out my beginner's guide to Pug. Mimogear's structure of pug comes with an awesome set of features:

• JSON powered navigation & gallery partial
• Ability to append stylesheets and scripts to specific pages
• Ability to customize title and description on specific pages

Sass, a pre processor for CSS, is souped up version of CSS with the power of variables, nesting, mixins, and functions. Mimogear comes packed with the following functions and mixins right from the get go which allow you to quickly:

• Visually hide/unhide elements,
• Clearfix rows,
• Establish max-width containers,
• Cover a child element over top of their container,
• Setup local font families,
• Calculate ems, rems and unitless numbers inline,
• And reset default list styles

Showin Those Muscles

A lot of love, a bit of elbow grease, and a bundle boilerplates went into Mimogear. This'll be the time to whip out a bottle of your favorite cola because we'll be gulpin, puggin, postin, scriptin our way to the moon and back!

Gulp Muscle

Right in the background of Mimogear resides a streamlined gulp file that manages all development asset workflows and separates development tasks from production tasks. This means production facing tasks such as minification are run on deployments rather than while you're building which gives you a pretty nice speed boost:

// Setup variables used to determine the environment
var dist = 'dist/',
    base = './' + dist,
    min = '',
    production = false;

// Grab the flag passed into the terminal after the gulp command
var options = minimist(process.argv.slice(2));

// Assign the environment variables based on the previously grabbed flag
if (options.base) base = './';
if (options.min) min = '.min';
if (options.production) production = true;

// Beginning of this sample stream represents the development environment.
// Continuation of this sample stream with flags represents the production environment:
.pipe(gulpif(production, uglify({
  mangle: false
})))
.pipe(gulpif(production, extReplace('.min.js')))
.pipe(gulpif(production, gulp.dest(dist + 'js')))
.pipe(gulpif(production, browserSync.stream()));

By using minimist, to extract flags from our terminal, and gulp-if, to conditionalize tasks, we can begin to separate our development and production facing environments. In the case of javascript, the main js file will only be uglified, renamed, and sent to the distribution folder only if gulp was flagged for the production environment.

Once you're all set up with automated deployments, the production flag will be triggered whenever there is a commit to your repository. To test how production facing tasks may run before they reach your production site, pass in the production flag right after the gulp command:

gulp --production

Pug Muscle

Hidden deep in the catacombs of Mimogear lies a complete pug boilerplate with all the partials, and mixins of the pugspace. To help make this boilerplate truly stand steady, there are some extra gulp tasks to complement pug. Gulp-changed, gulp-cached, and gulp-pug-inheritance work in unison, as a scalable solution, to make sure only the recently changed files are compiled. There's also an ignore line in gulp.src that allows you to create private draft pages by prefixing the page name with an underscore.

Now to help keep you focused on pages, Mimogear's template has you covered:

include mixins/image.pug
include mixins/gallery.pug
include mixins/symbol.pug
include mixins/section.pug

block theme
  - var themeName = ""

doctype html
html(
  lang="en"
  class=themeName
)
  include regions/head.pug
  body
    a.skip-link(href="#site-main") Skip to main content
    figure.site-sprite(style="display: none;")
      include ../../dist/svg/sprite.symbol.svg
    include regions/header.pug
    main.site-main#site-main(role="main")
      block content
    include regions/footer.pug

There's some pretty standard stuff in here, like the head, header, and footer partials but there's also a bit of spice mixed in. All the mixins available in Mimogear's mixin folder plus there's full access to a symbol sprite. Of course, there's a skip link too! Just a simple addition such as that can make our users feel at home ;)

Each page, on the other hand, is way simpler!

extends ../template.pug

block title
  - title = "Starter"

block content

Every page extends the base template, provides a place to change the browser's title tab, and presents a content block to add in any markdown or pug markup. Markdown is compiled using jstransformer-markdown and can be included by nesting markdown content into the :markdown filter. Pug markup can range anywhere between custom additions to mixin inclusions.

Sass Muscle

When you hop over to the Sass skeleton boilerplate, you'll get a fresh set of styles to accompany your quick start. This boilerplate uses a hyphenated BEM like syntax, a modified version of idiomatic css, and key styles to serve a platform agnostic approach.

You'll also find in there the mimo module styles, namely styles for a lightweight slideshow, lightbox, and drawer. There's even a handy little flexbox grid starter kit in there:

.grid {
  display: flex;
  flex-wrap: wrap;

  &:after {
    @mixin clearfix;
  }

  &-centered {
    align-content: center;
    align-items: center;
  }
}

  .column {
    float: left;
    width: 100%;
  }

  // Example column setup for columns 1-12 at the yatterman breakpoint
  @for $i from 1 through 12 {

    .column-yatterman-#{$i} {
      width: $i * (100% / 12);
    }
  }

Javascript Muscle

As you wander deeper into Mimogear's vast world, you'll find a neat bundle of javascript modules. Slideshows, lightboxes, triggers, and DOM creation abound! They use the modular pattern described in Todd Motto's "Mastering the Module Pattern" post to drive plugin development:

var El = (function() {

  var s = {};
  var o = {
    class: 'generated'
  };

  // Run through user settings and compare with El settings
  var override = function(options) {
    s = o;

    for (var key in options) {
      if (options.hasOwnProperty(key)) {
        s[key] = options[key];
      }
    }
  }

  // Create a new element given an object of options
  var create = function(kind, options) {
    override(options);

    // All of the secret Element Creation Spices!
  };

  return {
    create: create
  };

})();

By adding onto the javascript module pattern, When this module is initialized, an object of settings can be passed in. The s (user generated), and o (module defaults) objects help localize the settings for that instance using the override function. In the case of the El module, settings are used in the create function to represent a new DOM element:

var newEl = El.create('div', {
  class: 'my-class',
  innerHTML: 'Lots of Text',
  attributes: {
    anyLabel: 'value of this attribute',
    anotherLabel: 'value of this attribute'
  },
  on: ['click', functionToRun]
});

Which will assign newEl the following DOM element:

<div class="my-class" anyLabel="value of this attribute" anotherLabel="value of this attribute">Lots of Text</div>

Spicy Secrets

Mimogear has a bit spice on top of all its sweet sugar. Navigation, galleries, and deployments are handled up front.

Navigation is handled via a configuration.json file that provides navigation data to pug. This data is then passed to a navigation partial which generates markup based on that data.

Galleries are a new addition to Mimogear! I'm really excited about this because it's my first time handling a custom task with node. Any images that are in the images folder will be represented as an object and passed to the gallery partial in pug. There's also support for separating galleries into nested folders within the image folder!

Deployments are also new to Mimogear. After making your site, Mimogear provides a starter kit for deploying to github pages and surge.sh using Travis CI. If you really wanna whip up easy deployments, there's also documentation to help setup netlify.

Online editing through Prose.io is a result of the new deployment setup. Prose is used to edit and commit files on github. As soon as a commit is made within Prose, Travis CI will trigger a build and recommit to the github pages branch of your repository.

Try it out!

You may be snuggled up with Jekyll or cozying up to Pelican, but there's always some room for one more ;) Mimogear has some pretty thorough documentation to help you set sails with your new static site. If you're looking to speed away right now, here's a quick terminal snippet for ya:

git clone https://github.com/mimoduo/mimogear.git
cd mimogear
npm install
npm install gulp-cli -g
gulp

Mimogear will then whip up in your browser and you're officially ready to start building your new site!

Rock those Gears!

Over the course of this post you've learned so much! You've learned about:

• Gulp, Pug, and Sass
• How to conditionalize tasks in gulp using minimist & gulp-if
• How templates & pages can be setup using Pug
• How to setup a simple grid foundation using Sass
• How to use a javascript module pattern to override default settings

Static site generators have matured into ever evolving supreme beasts. Outside of Mimogear, a small & happy beast, there are tons out there to explore. There are even new articles out there, such as this one, to document their ever changing nature.

I encourage you, my fellow Mimodians, to adventure out into this brave new world and discover all the wonderful contributions to static site generators out there in the wild!