Get BEM!

If you interested in writing articles or helping with site — feel free to make pull-requests or creating issues with discussions.

This repository contains sources of getbem.com site.

Quick start

Install bower and gulp executables, if you are already not:

npm i bower gulp -g

Clone this repository and install depencies:

git clone https://github.com/getbem/getbem.com.git
cd getbem.com
npm i
bower i

Build site:

gulp build

Open dist/index.html file:

open dist/index.html

Windows system have no open command, so try to open compiled dist/index.html file with your favourite browser.

Build steps explained

To build this site we are using gulpjs — which is extremely fast and extensible build system. We recommend to read the docs or watch Gulp — The Basics turtorials.

We will look at main parts of gulpfile.js, which are:

• CSS
• HTML
• JavaScript

These task was intentionally simplified to keep things small.

Before digging into tasks, we will take short introduction in gulp-bem which is used in all tasks.

gulp-bem

If you familar with building of BEM projects — then you probably know, that BEM projects have certain structure: file with CSS for blocks will be in block folder with name {block}.css (where {block} is placeholder for current block name). All blocks are grouped to levels — folders with blocks.

With this structure is not clear in which order you should concatenate blocks and how get specific files from block (element or modifier) folder. To make it easy - we wrote gulp-bem.

Main object, that powers gulp-bem is bem-object. You can explore readme in bem-object repository, but in short — it represents directory with files (or single file for modifier with value case). To get all bem-objects from level you can do bem.object('level') - it will return Stream of bem-objects.

gulp-bem also provides *.deps.js files support. They are used to define dependencies between blocks. You can read gulp-bem-specs with explanations.

When talking about dependencies - it is always good to imagine dependencies tree. gulp-bem provides a way to construct those trees and query them for linearized dependencies:

var tree = bem.objects(levels)
    .pipe(bem.deps())
    .pipe(bem.tree());

To construct tree of dependencies - you need to read deps file - we get you covered, and bem.deps() reads file that named {bem}.deps.js from bem-object (where {bem} is BEM identificator for current bem-object).

After tree is constructed — you can query dependencies of block: tree.deps('block') which return Stream of bem-objects. Usually it is used for building dependency tree for single page.

CSS

To build CSS you don't need magic — it just concatenation of {bem}.css files in right order:

tree.deps('levels/pages/index')
    .pipe(bem.src('{bem}.css'))
    .pipe(concat(page.id + '.css'))
    .pipe(gulp.dest('./dist'));

bem.src('{bem}.css') takes bem-object and extracts all files, that matches argument. In this example it will get all CSS files with same name as BEM entity.

But, if you want to get CSS files for every page (which itself is a block), you need to get all pages objects and run building for each of them:

gulp.task('css', function () {
    function buildCss(page) {
        return tree.deps('levels/pages/' + page.id)
            .pipe(bem.src('{bem}.css'))
            .pipe(concat(page.id + '.css'))
            .pipe(gulp.dest('./dist'));
    }

    return bem.objects('levels/pages').map(buildCss);
});

HTML

This is tricky part of getbem.com. At first we try'd to use bh as templating language — but quickly realize, that it is too complex to achieve fast development and quick prototyping of site.

So we used Jade and it's mixins to achieve reusablility of templates from blocks.

In short, block can contain {bem}.jade file with mixin:

mixin author(avatar, name, link)
  .author
    a.author__link(href=link)
      img.img.img_circle.author__photo(src=avatar)
      span.author__name
        = name

After you get this code in main Jade template, you can call it:

+author('some', 'sweet', 'parameters')

We just get addicted to Jade after some time with it. Here is part of task, that compiles Jade template for index page:

return tree.deps('levels/pages/index')
    .pipe(bem.src('{bem}.jade'))
    .pipe(concat({
        path: 'index.jade',
        base: 'levels/pages/index'
    }))
    .pipe(jade({pretty: true}))
    .pipe(gulp.dest('./dist'));

Tricky part is get right base path for concatenated file:

concat({
    path: 'index.jade',
    base: 'levels/pages/index'
})

If you miss base property, then extend and include in Jade template will not work.

Again, to build all pages with Jade, we using this code:

gulp.task('html', function () {
    function buildHtml(page) {
        return tree.deps('levels/pages/' + page.id)
            .pipe(bem.src('{bem}.jade'))
            .pipe(concat({
                path: page.path + '/' + page.id + '.jade',
                base: page.path
            }))
            .pipe(jade({pretty: true}))
            .pipe(gulp.dest('./dist'));
    }

    return bem.objects('levels/pages').map(buildHtml);
});

Warning: Jade is not quite suited for processing concatenated templates from different files — so line numbers in error messages will be strange.

JavaScript

Building JavaScript is very hard task to do. We used our wrapper around browserify — gulp-bem-pack. It add to browserify ability to require modules from BEM Levels — which is kind of equivalent of cascading in CSS.

Task to do it is quite short (because we building it only for index page in our case):

gulp.task('js', function () {
    return tree.deps('levels/pages/index')
        .pipe(bem.src('{bem}.js'))
        .pipe(pack('index.js'))
        .pipe(gulp.dest('./dist'));
});

We are looking forward to use Duo, as soon as resolving parts will be configurable.

Development

First, clone this repo and install dependencies:

git clone https://github.com/getbem/getbem.com.git
cd getbem.com
npm i
bower i

After you cloned repo and installed requirements, you can start development server:

gulp

It will build site, start watcher on files and start local server on localhost:4000.

When you are sure about changes (and if you can push in this repository), you can publish getbem.com:

gulp gh

MIT License