Docpad with the taste of BEM
Let me present a stub for docpad-run project with
bem-built static assets. If you ever wanted to be
a generic blog holder equiped with nice and neat static
files, here we go.
How to start
You need install the docpad first. Follow their Installation Guide.
Then, the installation of the blog is super short and easy. Clone, fork or copy from the docpad-bem-stub repository. Then, go though the 3 installation steps:
npm install ./node_modules/bower-npm-install/bin/bower-npm-install docpad run
With these 3 steps you will get:
- a local server with a generic docpad blog;
- fully tuned static-build instructions which run on changes in your source code;
- initial blog structure.
How to write
In the given structure you can write either pages or blog posts. The posts are listed in the index page. Once you added a new item, you can see it in this list and navigate to its page; the docpad rebuilds from source automatically.
Place the pages as
*.html.md files into
directory. The posts are kept into
How to develop statics
The statics is developed with BEM.
desktop.bundles directory. The pages are built with blocks
The rebuild process for statics runs under docpad server.
Sometimes you may prefer to develop static pages separately. For this run
You will get another server which rebuilds statics. It
produces static html files from
*.bemjson.js files in
desktop.bundles. You can develop the layout inserting
json there and providing
BEMHTML templates for the
corresponding block. Find the documentation about
For the same blocks you can provide
and get them built into pages.
How to publish
The blog is tuned to be deployed on GitHub. Thus, your
repository has to be named as
can develop in its
source branch. For deploying on
<username>.github.io host run this command:
This will create
master branch of the repository whose
source is linked to the host.
You can also attach your own domain to the blog like I did.
Also, it is possible to host your blog in differently named
repository. However this will make you to provide changes
docpad.coffee configuration file.
Study Github Pages to learn more.
This blog had been running on Jekyll for a while. This was an
acceptable soltuion for a quick start. However with the growth
of the posts base I started to suffer from not very fast
rebuilds. Also, sometimes providing changes into the blog
layout was hard, mostly due to the limitations of
I've decided that Docpad should be much better alternative. It is served as an npm package, possible to be extended with plugins and has an active fast-growing developers community.
docpad-bem-stub gives you initial structure, from which
you already can write and publish. If you want to provide changes
into the build process, modify the templates or extend with
plugins, learn at Docpad website.
Moreover, Stackoverflow indeed already has an answer to almost all the questions you have. If not, create a new one.
Above I described all you need to know for using your blog. Below there are a little more technical details on what is behind.
I use enb for building pages with block components. This solution is preferable to bem-tools because of it is much faster. When rebuilding pages on every change, this is sensetive.
i-bem.js and modules
I personally love that this solution brings
i-bem.js library to the
project. Hope to demonstrate its amazing capabilities here in near future.
can see some examples and very detailed explanations in Step-by-step tutorial on
As mentioned above,
these templates can be applied on both server and client side. There are
a couple of documents for a deeper dive into it here:
bem-core and bem-components
BEM is also nice for a possibility to borrow the components from libraries.
docpad-bem-stub uses 2 now available libraries:
I hope to see more in the future.
Indeed everything can be improved. These are my thoughts on how to continue.
- detect changes in static files
Docpad watches over the changes in
srcdirectory. This means that when developing statics you will not get the rebuild. I am thinking on running
docpad runand proxy. This maybe better than watch over a lot of files in
desktop.bundlesand all the libraries.
- css preprocessors
The blog styles are in pure CSS now. But with a little change into enb configuration we can learn it to build with preprocessors.
- fresh design
Creating a simple layout is the most difficult design task. Don't you agree?
- nice initial posts
This is even harder than the desing tasks but I think the users feel much more comfortable when getting a blog with predefined texts.
If you feel your oats and want to do your bit, fork the repository and start :-)