To get the nice dash before our citation, Bootstrap requires that we place it in a <footer> tag, which is fine, but Markdown doesn't offer this capability for us. It does allow us to write HTML inline instead, but that isn't very portable; what if we migrate to another framework that doesn't use this HTML? Well, we end up having this HTML forever in our Markdown files.

That doesn't sound very appealing. So, what we'll do instead is use cheerio and write a custom renderer for marked to automate the process for us; all we have to do from now on is write blockquotes in Markdown format, and it will be converted into our custom HTML automatically.

I couldn't tell you in any detail how my computer works. I use it with a layer of automation.

In Markdown, this quote would look like the following:

> I couldn't tell you in any detail how my computer works. I use it with a layer
> of automation.
>
> --[Conrad Wolfram][1]

We want to generate the following output:

<blockquote>
    <p>I couldn't tell you in any detail how my computer works. I use it with a
    layer of automation.</p>
    <footer>
        <a href="http://www.wired.co.uk/news/archive/2012-06/28/conrad-wolfram-computation">Conrad Wolfram</a>
    </footer>
</blockquote>

In my case, I'm using metalsmith to transform the Markdown into HTML, but the renderer logic will be the same as for any other set up. Here's the code for that:

var cheerio  = require('cheerio');
var renderer = new (require('marked')).Renderer();

renderer.blockquote = function (text) {
    var $ = cheerio.load('' + text);
    $('p').each(function () {
        if ($(this).text().indexOf('--') === 0) {
            var html = $(this).html().replace('--', '');
            $(this).replaceWith($('<footer>' + html + '</footer>'));
        }
    });
    return '<blockquote>' + $.html() + '</blockquote>';
};

Here, we load the HTML into the cheerio parser, and then check each paragraph inside which starts with --. We then wrap that paragraph with the <footer> tag, and strip away the double dashes (which are replaced by a dash in the CSS).

All we have to do now is pass that renderer to metalsmith-markdown:

var Metalsmith = require('metalsmith');
var markdown   = require('metalsmith-markdown');

Metalsmith(__dirname)
    // ...
    .use(markdown({ renderer: renderer }))
    // ...
    .build(function (err) {
        if (err) {
            throw err;
        }
    });

We now have automatic <footer> generation for blockquotes, site-wide; and if the CSS framework is changed to one that does not require this tag, it is as easy to remove.

Check out the full build process for my blog, which uses this technique.

Working in a well-organized code base is like cooking in a clean kitchen. If things feel messy, it’s easy not to treat it with respect. If the formatting feels sloppy, it will tempt you to also be sloppy when it comes to readability, dependency management, and testing.

I found myself agreeing with many points raised in Why Does Style Matter?; indeed, I've discovered the benefits of consistent formatting only within the last few years. Code just looks neater when it is formatted consistently; if you write it the same way every time, people who are unfamiliar with your code won't get put off by the lack of consistency. As an example, this looks really messy:

$('#email').blur(function()
{
    var email = $(this);
    valid = validate_input(email.val(), 'email address', {
        required:true,
        email:true
    });
    if (!valid) {
        validate_message(email,'#email-check',valid);
    }
    else {
        $.getJSON("http://api.mywebsite.com/users/" + email.val() + "?callback=?", function(e) {
            if (e.email===email.val()) {
                validate_message(email,'#email-check','Your email address is already registered!');
            }
            else
            {
                validate_message(email,'#email-check','OK');
            }
        });
    }
});

The lack of formatting consistency doesn't aid readability, especially in this jQuery soup. We can do a little better without having to change the logic in the code:

$('#email').blur(function () {
    var email = $(this);
    valid = validateInput(email.val(), 'email address', {
        required: true,
        email: true
    });
    if (!valid) {
        validateMessage(email, '#email-check', valid);
    } else {
        $.getJSON('http://api.website.com/users/' + email.val() + '?callback=?', function (e) {
            if (e.email === email.val()) {
                validateMessage(email, '#email-check', 'Your email address is already registered!');
            } else {
                validateMessage(email, '#email-check', 'OK');
            }
        });
    }
});

And it's better still if we were to change the logic around and reduce line length:

$('#email').blur(function () {
    var email = $(this);
    var endpoint = 'http://api.website.com/users/' + email.val() + '?callback=?';
    var message;
    valid = validate_input(email.val(), 'email address', {
        required: true,
        email: true
    });

    if (valid) {
        $.getJSON(endpoint, function (e) {
            if (e.email === email.val()) {
                message = 'Your email address is already registered!';
            } else {
                message = 'OK';
            }
        });
    } else {
        message = valid;
    }

    validateMessage(email, '#email-check', message);
});

In most cases, work like this should be done by the developer writing the code; code review should be about finding issues with some code; whether it is a performance or maintenance concern, not taking the developer to task about their line lengths or repetitive code.

But to me, a service like Hound doesn't appeal, for a number of reasons. The main one is just that its helpful suggestions come too late in the process.

Set, and forget

Common tasks, such as removing trailing whitespace, setting line endings & indentation size/character can be done whilst the file is being edited, using EditorConfig. The nice thing about this is that it is really easy to set up complex whitespace arrangements for different file types; say if you edit Ruby code and want to stick to their 2 space indent convention, but for your SCSS you want 4 spaces. It's easy to define an .editorconfig file for this purpose:

# editorconfig.org
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

# 4 space indentation just for CSS
[*.scss]
indent_size = 4

With EditorConfig plugins, your text editor can always respect the project's code style decisions, & you can have different setups for each project, if you so wish.

More than just whitespace

But why stop at whitespace? Tools such as ESLint can check our source code for programmatic & stylistic errors. Want all of your variable and function names in camelCase? There's an option for that, and many others; the advantage of using these is that your computer is always analysing what you write, as you write it; mistakes can be fixed immediately, then and there.

For the perfectionist in us, there exists JSCS; an extremely thorough code style validator. Although it may seem a little daunting, it works best when starting a new project from scratch; using it on your existing projects may lead to you feeling overwhelmed.

Why wait to push your code to GitHub before a computer tells you that it could be improved upon?

<h1>Some title <span class="amp">&amp;</span> some other stuff</h1>

On a blog such as this one which uses Markdown for publishing, it's much cleaner to write this:

# Some title & some other stuff

That way, if the design is updated and the custom ampersands do not fit into the new look, the CSS can be removed & nothing else has to change!

Essentially the gist of the article is that you can specify a local font to use as an ampersand, then override it in Firefox. I am using this technique on this blog, but instead of using Arial as a fallback, I wanted to use the fonts that I already had in place. The code, then, is slightly more verbose:

/* Load the web fonts */

@font-face {
    font-family: Oxygen;
    font-style: normal;
    font-weight: 400;
    src: url(../fonts/oxygen-webfont.woff2) format("woff2"),
         url(../fonts/oxygen-webfont.woff) format("woff");
}

@font-face {
    font-family: Bitter;
    font-style: normal;
    font-weight: 400;
    src: url(../fonts/bitter-regular-webfont.woff2) format("woff2"),
         url(../fonts/bitter-regular-webfont.woff) format("woff");
}

/* Load the ampersand override */

@font-face {
    font-family: Ampersand;
    src: local(Baskerville-italic), local(Palatino), local(Book Antiqua);
    unicode-range: U+26;
}

@font-face {
    font-family: Ampersand Headings;
    src: local(Baskerville-italic), local(Palatino), local(Book Antiqua);
    unicode-range: U+26;
}

/* Load the ampersand fallback */

@font-face {
    font-family: Ampersand;
    font-style: normal;
    font-weight: 400;
    src: url(../fonts/oxygen-webfont.woff2) format("woff2"),
         url(../fonts/oxygen-webfont.woff) format("woff");
    unicode-range: U+270C;
}

@font-face {
    font-family: Ampersand Headings;
    font-style: normal;
    font-weight: 400;
    src: url(../fonts/bitter-regular-webfont.woff2) format("woff2"),
         url(../fonts/bitter-regular-webfont.woff) format("woff");
    unicode-range:U+270C;
}

/* Apply the fonts to body copy and headings */

body {
    font-family: Ampersand, Oxygen, Helvetica Neue, Helvetica, Arial, sans-serif;
}

h1 {
    font-family: Ampersand Headings, Bitter, Georgia, Times New Roman, Times, serif;
}

This way means that you can have a nice custom ampersand in supported browsers, & in Firefox the ampersand will gracefully degrade back to the webfont it was already using.

In this post we'll look at what measures we can take to reduce Bootstrap 3 down to only its necessary elements. Your mileage may vary, depending on how much of the framework you use; and to get the most out of Bootstrap you should be using a CSS preprocessor. Bootstrap is written in Less but there is also a Sass port, which I will be referencing in this article. Also note that some of these techniques are equally applicable to other CSS frameworks.

Put down pre-packaged builds. Hello Sass.

One of the first things we need to start with is customising our own version of Bootstrap 3. To get the most out of our stylesheets, we shouldn't be using pre-packaged builds that third parties provide to us as a convenience; they encourage us to put their CDN links first and then override the styling with our own rules. Unfortunately this means that we miss out on one of the best features of Bootstrap; its customisability.

However, this does not mean that we should all jump on over to the customise page for Bootstrap, with its myriad options. The likelihood is that all of the hex colours/font sizes that you input there will be consistent with other, custom components that you write yourself. Therefore, you should be defining them in your Sass files instead, making them reusable and easily modifiable.

The first step is to install the Sass version of Bootstrap. With Bower, we can simply do:

$ bower install bootstrap-sass-official

Next, we need to load it into our Sass files. But hold on; we need to start writing a build process which will end up handling all of our compilation and optimisation tasks, and ensure that we have a customised build of Bootstrap for our production site. For tasks such as these, gulp suits the job perfectly as a sequence of transformations can be applied to our CSS in memory. Once you have installed gulp globally, then install the other dependencies from npm:

$ npm install gulp gulp-ruby-sass@1.0.0-alpha chalk --save-dev

Our first iteration of our Sass task should just take the source files from the styles directory, compile them into CSS and then write them to a destination. In addition, if there were any errors, log them to the console:

var chalk = require('chalk'),
    gulp  = require('gulp'),
    sass  = require('gulp-ruby-sass');

gulp.task('styles', function () {
    return sass('./styles', {
        loadPath: './vendor/bootstrap-sass/assets/stylesheets'
    }).on('error', console.warn.bind(console, chalk.red('Sass Error\n')))
        .pipe(gulp.dest('./build/css'));
});

We define a loadPath here so that we can import Bootstrap into our stylesheets. So, in the ./styles directory, create a new file called main.scss and write:

@import 'bootstrap';

Now, when we run gulp styles, we will have the full Bootstrap 3 source code in the ./build/css directory. We are ready to start optimising.

Method 1: Include only necessary components

The simplest way to trim down the framework is just simply to customise which @import statements that you carry over into your main CSS file. You can do this by changing the contents of main.scss to something like this:

// Core variables and mixins
@import "bootstrap/variables";
@import "bootstrap/mixins";

// Reset and dependencies
@import "bootstrap/normalize";
@import "bootstrap/print";
@import "bootstrap/glyphicons";

// Core CSS
@import "bootstrap/scaffolding";
@import "bootstrap/type";
@import "bootstrap/code";
@import "bootstrap/grid";
@import "bootstrap/tables";
@import "bootstrap/forms";
@import "bootstrap/buttons";

// Components
@import "bootstrap/component-animations";
@import "bootstrap/dropdowns";
@import "bootstrap/button-groups";
@import "bootstrap/input-groups";
@import "bootstrap/navs";
@import "bootstrap/navbar";
@import "bootstrap/breadcrumbs";
@import "bootstrap/pagination";
@import "bootstrap/pager";
@import "bootstrap/labels";
@import "bootstrap/badges";
@import "bootstrap/jumbotron";
@import "bootstrap/thumbnails";
@import "bootstrap/alerts";
@import "bootstrap/progress-bars";
@import "bootstrap/media";
@import "bootstrap/list-group";
@import "bootstrap/panels";
@import "bootstrap/responsive-embed";
@import "bootstrap/wells";
@import "bootstrap/close";

// Components w/ JavaScript
@import "bootstrap/modals";
@import "bootstrap/tooltip";
@import "bootstrap/popovers";
@import "bootstrap/carousel";

// Utility classes
@import "bootstrap/utilities";
@import "bootstrap/responsive-utilities";

Lets say that you aren't going to use the JS components in your application. Well, just simply delete the relevant @import statements, and already your build is looking smaller. But, six months later on, you may want to add some of these back in to your build, as your requirements may change, so this approach may not scale well.

Method 2: Use UnCSS to determine which classes are being used

A more scalable version of the above is to use UnCSS, a tool that find unused CSS rules by analysing them against the HTML of your website. I wrote a gulp plugin for UnCSS which allows us to do the same thing in our build:

$ npm install gulp-uncss --save-dev

Depending on the size of your site, it probably won't be feasible to run this tool whilst you are developing. Instead, have a separate UnCSS task that you can run before deploying to production, like so:

var uncss = require('gulp-uncss');

gulp.task('uncss', function () {
    return gulp.src('./build/css/main.css')
        .pipe(uncss({
            html: ['./build/**/*.html']
        }))
        .pipe(gulp.dest('./build/css'));
});

Note that UnCSS does not detect classes that are added by user interaction, so if you are to use any JavaScript components from the framework then you must pass an ignore list to UnCSS. Even so, especially on small sites, UnCSS makes a huge difference to the size of the output file.

Method 3: Use combine-mq to eliminate duplication of media queries

Because of Bootstrap's expansive size, its CSS rules must be grouped together into logical components; this is also true of the media query selectors that it uses. There are many media query breakpoints that are repeated over and over, adding weight to the CSS file. To optimise this, we can use gulp-combine-mq, which will remove duplicates.

$ npm install gulp-combine-mq --save-dev

We'll add this to our default styles task:

var combinemq = require('gulp-combine-mq');

gulp.task('styles', function () {
    return sass('./styles', {
        loadPath: './vendor/bootstrap-sass/assets/stylesheets'
    }).on('error', console.warn.bind(console, chalk.red('Sass Error\n')))
        .pipe(combinemq())
        .pipe(gulp.dest('./build/css'));
});

Method 4: Use autoprefixer to include only necessary vendor prefixes

Autoprefixer is a tool that adds vendor prefixes to unprefixed CSS properties, and is based on the excellent Can I use... database. This means that we only have to include prefixes for browsers that still need them, and redundant properties are dropped from the resulting stylesheet. So, in a few years time, when Browser X supports a feature unprefixed and usage of the older versions declines to a less than relevant installed percentage, Autoprefixer will know to not supply the prefix for that browser. It also means that when authoring your SCSS, you don't need to write the vendor prefixes yourself. It's an easy win.

$ npm install gulp-autoprefixer --save-dev

Again, add this to the default styles task:

var autoprefixer = require('gulp-autoprefixer');

gulp.task('styles', function () {
    return sass('./styles', {
        loadPath: './vendor/bootstrap-sass/assets/stylesheets'
    }).on('error', console.warn.bind(console, chalk.red('Sass Error\n')))
        .pipe(autoprefixer())
        .pipe(combinemq())
        .pipe(gulp.dest('./build/css'));
});

Method 5: Use variables for customising, rather than writing more selectors

Let us return to customisability. Writing more selectors for Bootstrap to define things like a different button colour, or a different form control style can lead to bloat. Instead, before we do any of that, we should customise the base framework and only include our own custom components when necessary. At this point, I like to extract the variables part of main.scss out into its own file - so that main.scss now looks like this:

@import "variables";

// Reset and dependencies
@import "bootstrap/normalize";
@import "bootstrap/print";
@import "bootstrap/glyphicons";

// ... etc

And then, we can have a _variables.scss file in which variables are defined:

$body-bg: #000;
$text-color: #fff;

// Core variables and mixins
@import "bootstrap/variables";
@import "bootstrap/mixins";

This code customises Bootstrap with a black background and white text, without us having to write another selector. For simple customisations like this, have a look in your copy of Bootstrap Sass for the _variables.scss file. In here you will find all of the variables so that you can change the appearance of Bootstrap to your liking.

Method 6: Get a good minifier

There exist a plethora of CSS minification tools for JavaScript. In my opinion, the best ones offer selector and declaration consolidation; such that CSS like this:

body {
    color: red;
}

body {
    background: #fff;
}

Will be minified to this:

body{color:red;background:#fff}

This is useful when you are using a framework; what happens if you need to add a property to an element/class that already exists in Bootstrap, but can't edit the Sass file for obvious future compatibility reasons? Well, you can let a minifier do the work for you. gulp-css-condense uses these techniques to minimise your CSS structure. Other good minifiers include gulp-csso, gulp-more-css and gulp-cssshrink.

I've found that because each of these compressors offer different functionality, it's possible to extract the most compression out of your CSS by using multiple compressors. We can do that easily in gulp:

$ npm install gulp-css-condense gulp-csso gulp-more-css gulp-cssshrink --save-dev

var cssc   = require('gulp-css-condense'),
    csso   = require('gulp-csso'),
    more   = require('gulp-more-css'),
    shrink = require('gulp-cssshrink');

gulp.task('styles', function () {
    return sass('./styles', {
        loadPath: './vendor/bootstrap-sass/assets/stylesheets'
    }).on('error', console.warn.bind(console, chalk.red('Sass Error\n')))
        .pipe(autoprefixer())
        .pipe(combinemq())
        .pipe(cssc())
        .pipe(csso())
        .pipe(more())
        .pipe(shrink())
        .pipe(gulp.dest('./build/css'));
});

Now, when we run the styles task, we will get a autoprefixed, media query combined, aggressively optimised CSS file. Great!

Extracting compression methods with lazypipe

We're not quite done here. You will notice that our UnCSS task does not run any of the minification tasks - because it isn't a minifier itself the output looks closer to the Sass as we started writing it, although the overall size is smaller. But wait, before you start copying and pasting the pipe() chain from the styles task, you can use lazypipe!

$ npm install lazypipe --save-dev

Using lazypipe allows us to create an immutable stream 'factory'. Basically it means we are creating a pipeline that we can hook into in our various gulp tasks. We can use it like so:

var cssOptim = lazypipe()
    .pipe(cssc)
    .pipe(csso)
    .pipe(more)
    .pipe(shrink);

gulp.task('styles', function () {
    return sass('./styles', {
        loadPath: './vendor/bootstrap-sass/assets/stylesheets'
    }).on('error', console.warn.bind(console, chalk.red('Sass Error\n')))
        .pipe(autoprefixer())
        .pipe(combinemq())
        .pipe(cssOptim())
        .pipe(gulp.dest('./build/css'));
});

Note that we don't call the cssOptim function until we need it in our styles task. We can now reuse that pipeline for any other tasks that might want to process CSS, such as UnCSS. So our final gulpfile should look like this:

var autoprefixer = require('gulp-autoprefixer'),
    chalk        = require('chalk'),
    combinemq    = require('gulp-combine-mq'),
    cssc         = require('gulp-css-condense'),
    csso         = require('gulp-csso'),
    lazypipe     = require('lazypipe'),
    more         = require('gulp-more-css'),
    gulp         = require('gulp'),
    sass         = require('gulp-ruby-sass'),
    shrink       = require('gulp-cssshrink'),
    uncss        = require('gulp-uncss');

var cssOptim = lazypipe()
    .pipe(cssc)
    .pipe(csso)
    .pipe(more)
    .pipe(shrink);

gulp.task('styles', function () {
    return sass('./styles', {
        loadPath: './vendor/bootstrap-sass/assets/stylesheets'
    }).on('error', console.warn.bind(console, chalk.red('Sass Error\n')))
        .pipe(autoprefixer())
        .pipe(combinemq())
        .pipe(cssOptim())
        .pipe(gulp.dest('./build/css'));
});

gulp.task('uncss', function () {
    return gulp.src('./build/css/main.css')
        .pipe(uncss({
            html: ['./build/**/*.html']
        }))
        .pipe(cssOptim())
        .pipe(gulp.dest('./build/css'));
});

Putting it into practice

Why blog about this kind of optimisation if its not something that you're going to use? So, behold! This blog is using all of the techniques covered in the article; pay attention to the CSS source code and you'll notice that there are many familiar styles in there to describe columns, and header navigation; but many of the helper classes and columns/components that are unused have been stripped away, leaving only what the blog needs.

In closing, remember that although this article is focused on Bootstrap, these techniques can (and should!) be applied to CSS whereever it may be used. The amount of tooling that we can use to perfect our stylesheets should be taken advantage of, as every optimisation means a faster, better website experience for you and your users.