Welcome to Moka

Moka is a damn simple framework designed to build static websites like portfolios, showcases, minisites, HTML mockups, etc. Moka setup takes a single command, and it provides a hierarchical template system and some hyper-convenient helper functions so you never have to write more code than necessary. The result of your work is compiled to plain HTML, CSS and Javascript, so you just have to upload it to your server. Plus, don’t forget the Lipsum helper functions to generate dummy text with a single line of code during development or in HTML mockups.

A taste of Moka coolness:

• Don’t Repeat Yourself

• Convention Over Configuration

• Learn it in 10 minutes, set it up with a single command, start your creative work!

• Compile everything into plain HTML and CSS code, working on virtually every possible webserver

Installation

Install the gem:

sudo gem install moka

Getting Started

Prerequisites

Moka is really simple and straightforward, but it is intended for developers and people who already know how to code in HTML and CSS. Since Moka uses Ruby language, some knowledge of it is probably needed before getting started. For Ruby on Rails developers, using Moka should be extremely simple, since Moka uses erb (or haml) and many helper functions that work nearly the same way as in Rails.

Create a new Moka project

You can create a new Moka project with just one command. Simply navigate to your development directory, open the command line and type:

moka new site your_site_name

You need to replace ‘your_site_name’ with the actual name of your project.

By the time this command executes, you’ll see that a new directory named ‘your_site_name’ (or whatever you choose as the name of your project) was created. Into this directory you will see a file named manifest.yml, which describes the structure of your new site and gets updated automatically as you create new pages and groups. Apart from this file, you will find three directories:

* compiled - here is where your project will be compiled to a pure HTML website, and where static assets like images, javascripts and stylesheets should be placed.

* project - your development directory, where you will create all the pieces that Moka will put together to compile your project into a working website: partials, variables, groups and pages (keep reading and this will get much clearer)

* script - this directory contains files needed by Moka in order to work properly. Usually you won't need to edit them.

Add pages to your website

Adding pages to your project is really simple, but first you need to understand the way Moka is organized. In Moka we have the concepts of site, groups and pages. Basically, every page belongs to a group, and every group belongs to the site. It’s like a tree: the site is the root, groups are branches and pages are leaves (for this reason we call this structure the sitetree).

This structure helps you avoid duplication and write less code: if some pages share some common elements, such as layout or pieces of code, they should belong to the same group. This way, you will need to code the common elements just once, at the group level, and all the pages in that group will use them. In the same way, if some elements are common to all the pages in your website, you should code them at the site level, so they will be available to every page in every group.

Groups also determine the location in which pages will be compiled. In particular, a page named ‘hello’ belonging to a group named ‘greetings’ will be compiled by default in /greetings/hello.html into the compiled directory. This rule is always valid, apart from the default group, which is named ‘root’ and gets compiled in the root directory. In other words, if you create a new page named ‘welcome’ without specifying the group it belongs to, it will belong by default to the group ‘root’, and will be compiled in /welcome.html (and NOT in /root/welcome.html).

So, let’s get more practical and create the first page in our project. In the command line, navigate to your new project directory and type:

moka new page index

Bazinga! You just created a new page named ‘index’ and belonging to the group ‘root’. Want to see it? You can have a look at it in your browser, but since this page is not yet compiled, you first need to start the development server. Again, type in your command line:

moka server

Now, as soon as the WEBrick server starts, you can open your browser, go to localhost:3333/index.html and see the page you just created. The development server is a very useful tool, since it shows you a preview of your work without having to re-compile the whole site after each change. Still, keep in mind that it is quite slow and only intended for development: before publishing your website you will have to compile it into HTML and CSS code.

In the previous example, we didn’t specify a group, so Moka created the page named ‘index’ in the default group, a.k.a. ‘root’. In order to create a new page named my_page in a group named my_group you would have instead to type in the command line:

moka new page my_group:my_page

Customize pages

Now that you created your first page, you probably want to edit its layout and content to suit your needs. It is then time to open the text editor of your choice and start coding.

But what files do you need to create/edit? When you create a page using the new page command, Moka creates into the project/site directory a new directory named as the group your page belongs to (‘root’ if you didn’t specify it), and into that it creates another directory named as the page. Also, it updates the manifest.yml file with the info about the new group and page. Note that the directories are structured as a tree (the sitetree, again): the site directory contains the group directories, and each of these group directories contains the directories of pages belonging to that group.

All the files you need to create or edit to change the HTML code of your new page are placed in these new directories. But where precisely?

Think of pages in a Moka project as jigsaw puzzles: every page is composed of various pieces, and Moka uses its conventions in order to select the right pieces when assembling the puzzle. When Moka compiles a page, first of all it looks for a file named layout.erb (or .haml) which defines the basic HTML layout and structure of the page. Moka looks for this file first in the page directory (project/site/root/index in the case of our first page). If it can’t find it there, it looks into the group directory (project/site/root), and then, if there is no layout file in the group directory, it looks for it in the site directory (project/site).

Apart from defining the basic HTML structure of a page, the layout file may request one or more partials (through the Ruby method partial(:partial_name) ). As the name indicates, partials are simply parts of the HTML code of a page, or pieces of the puzzle in our analogy. As it does with the layout file, Moka looks for each partial first in the page directory, than in the group directory, and finally, if all else failed, in the site directory.

In your layout or partials, you can also use some variables, that you define in a file named variables.yml. Again, Moka decides the value of each variable looking for its definition (in a variables.yml file) first in the page directory, then in the group directory and finally in the site directory until it finds it.

Now the advantage you get from this hierarchical structure provided by Moka should be clear: you place all the page-specific elements in the page directory, the elements that are used in multiple pages in the same group in the group directory, and all the elements that are used by many pages all over the site in the site directory. Moka always assembles your pages using the most specific elements (layout, partials and variables). This means that you never have to write duplicated code.

Pagetree variables

In your layout and partials you have access to some instance variables. These are @site, @current_group and @current_page. As the names suggest, these variables point to the current page, group and site in the sitetree. The same layout or partial may be used by many different pages, but when you compile your project, the @current_page (@current_group) variable will always be referencing the right page (group) being compiled. You can navigate through them:

@site.groups # Returns an Array of all groups
@current_group.pages # Returns an Array of all pages in the current group
@current_page.group # Returns an object referencing the group to which @current_page belongs. Same as @current_group
@site.mygroup.mypage # Returns an object referencing the page 'mypage' in group 'mygroup'
@site.find_group('mygroup').find_page('mypage') # Same as above, but the strings passed as arguments to the find_*
                                                # methods may be variables declared somewhere else in your code

The object in the sitetree (site, groups and pages) let you access the variables defined in the variables.yml files. Thus, you can do something like:

@current_page.name # The name of the current page. 'index' in the case of our first example.
@current_page.my_variable # Returns the value of variable my_variable defined in the variables.yml file in the
                          # current page directory, or in its group directory, or in the site directory.

Making good use of sitetree nodes and their variables you can easily employ page-specific values in your code.

Helpers

Moka provides you with a bunch of super useful helper methods that you can use in your layouts and partials. Some of these helpers are link_to, path_to, image_tag, include_javascript_tag, stylesheet_link_tag and many more (Rails developers, do some of these methods sound familiar?). Read the docs and find out how these methods can help you making your code extremely efficient.

Need even more kung fu? Then you can code your own helper methods. Just code your methods into project/lib/helpers.rb and you will be able to use them in your layout and partials.

Writing CSS

You are probably wondering now “OK, but what about CSS?”. Well, you can code your CSS inline or place CSS files into the compiled/stylesheets directory and import them in your HTML. Alternatively, if you are a fan of the awesome SASS syntax, you can write SASS or SCSS files into the project/styles directory, and they will be magically compiled into CSS stylesheets into compile/stylesheets.

Compiling the project into a website

When you finished coding your pages (which, thanks to Moka awesomeness, look like haiku poetry) you are ready to release your website. It is as simple as typing:

moka compile

Moka will compile all your project code into pure HTML and CSS into the compiled directory. In order to publish your new website you just have to upload the content of the compiled directory on your server. It’s so simple, and it just work!

More Moka awesomeness

Try to type in the command line something like:

moka new site --template=another/project/path  # Create a new moka project using another one as a template
moka new group [--template=another_group]  # Create a new group [using an existing one as a template]
moka new page my_group:my_page -v title:"My Page Title" exclamation:yeah!  # Create a page named my_page in group my_group
                                                                           # and define its variables title (with value "My 
                                                                           # Page Title") and exclamation (with value "yeah!")
moka inspect site  # Show groups and variables defined at the site level
moka inspect group my_group  # Show pages and variables defined at the level of group my_group
moka inspect page my_group:my_page  # Show variables defined at the level of page my_page in group my_group