Bobkit - Site Generation Toolkit

Bobkit is a lightweight toolkit for generating static websites with:

`Slim + SCSS + CoffeeScript + Markdown + I18n`

The design intentions were to:

Provide easy to use wrapper methods for Slim, SCSS, CoffeeScript and Markdown.
Not impose any directory structure (this is not another blog generator...).
Allow you to use standard ruby for generating your site how you see fit.
Be packaged as a library, and not a command line tool.
Provide sensible default locations that are easily overridable.
Add render and layout support to Slim (Rails-like).
Add i18n support to Slim (Rails-like).
Add @import 'globbing/*' support to SCSS (Rails-like).

Install

gem install bobkit

Or with Bundler:

gem 'bobkit'

Usage

The basic usage pattern is this:

Create a ruby file and include Bobkit
Create your input folders (for Slim templates, SCSS files etc.) wherever you want (or use the default locations, see below).
In your Ruby script, call Bobkit methods to generate your site.

Example

require 'bobkit'
include Bobkit::Tasks

# Convert Slim to HTML string
html = render 'youtube', video: 'hi9tOILaiNs'
puts html

# Convert Slim to HTML file
# This will use 'templates/youtube.slim', with the layout file
# `templates/layouts/default.slim` and will generate 'output/bobcat.html'.
render 'youtube', layout: 'default', video: 'hi9tOILaiNs', output: 'bobcat'

# Compile SCSS
# This will convert `styles/main.scss` to `output/css/style.css`
compile_css 'main', output: 'style'

See more examples in the Examples folder

DSL or Instance

Bobkit was primarily designed as a DSL, but if you wish to use a more scoped approach, you can use an instance of the Bob class.

require 'bobkit'

# Option 1: DSL
include Bobkit::Tasks
render ...
compile_css ...

# Option 2: Bob class
bob = Bob.new
bob.render ...
bob.compile_css ...

Reference

Setting folder locations and options

Bobkit has defaults for everything, but you can easily change them. Each of these methods can be called with or without a parameter. When called without a parameter, it will simply return the value.

# Base location of all other folders. Default: "."
root_folder 'my_app'

# Location of source Slim templates. Default: "templates"
templates_folder 'views'

# Location of source Slim templates for layouts. 
# Default: "#{templates_folder}/layouts"
layouts_folder 'my_layouts'

# Location of markdown files. Default: "markdown"
markdown_folder 'docs'

# Location of the source SCSS files. Default: "styles"
styles_folder 'styles'

# Location of locale configuration files. Default: "locales"
locales_folder 'locales'

# Output location. Default: "output"
output_folder 'site'

# Output location for CSS. Default: "#{output_folder}/css"
css_output_folder "#{output_folder}/stylesheets"

# Location of other source asset files (images etc.). Default: 'assets'
assets_folder 'files'

# Output location for assets. Default: "#{output_folder}/assets"
assets_output_folder 'images'

# Options for Slim generation.
slim_options pretty: true, disable_escape: true

# Options for SCSS generation.
scss_options cache: true, syntax: :scss, style: :nested

# Restore all settings to defaults
use_defaults

Slim

# You can set a scope before calling any `render`
scope CatVideo.new
html = render 'cats'

# You can use a hash as scope
scope email: 'bob@kit.com', name: 'Bob'
html = render 'user'

# You can render an object that responds to 'to_partial'
# This method should return the name of the partial file
user = User.new
html = render user

# You can send a scope directly to `render`
html = render 'user', email: 'bob@kit.com', name: 'Bob'

# You can render with a layout
html = render 'user', layout: 'default', email: 'bob@kit.com'

# You can save to a file in the `output_folder`
render 'user', layout: 'default', email: 'bob@kit.com', output: 'bob'

# You can send an HTML string as the content of a layout
render content: "<h1>Hello</h1>", layout: 'default'

In addition, you can call = render 'template' from inside a slim template.

To check if a certain context variable was provided to a slim template, you can use if have? :varname.

SCSS

# You can compile SCSS to a CSS string, to do as you please with it
css = compile_css 'style'

# You can compile SCSS directly to a file
compile_css 'style', output: 'main'

CoffeeScript

# You can compile CoffeeScript to a Javascript string
js = compile_js 'script'

# You can compile CoffeeScript directly to a file
compile_js 'script', output: 'main'

Markdown

# Compile a markdown file to HTML string
html = markdown 'article'

# Compile directly to a file, inside a slim layout
markdown 'article', layout: :default, output: 'article'

# All options pass through directly to the slim renderer
html = markdown 'article', layout: :default, sidebar: true

Asset helpers

Anything other than CSS, Javascript and HTML is considered an asset. These are some helpers to help you move them around from input to output folders.

# Copy a file from the `assets_folder` to the `assets_output_folder`
copy_asset 'presskit.zip'

# Copy a folder
copy_asset 'images'

Internationalization (I18n)

Bobkit supports these i18n features:

Set the folder for your localization files with locales_folder (default: 'locales').
You can call = t('common.hello') from a slim template.
You can call = l(Time.now) from a slim template.
Any call to render 'template_name' will first look for a localized version of the file (template_name.en.slim) and will use it if found. Otherwise, it will use the unlozalized filename (template_name.slim).

Low level file and folder helpers

If you want more control over what the copy_asset method provides, you can use any of these methods.

# Copy a file - needed parent folders will be created as needed
copy_file 'exact/path.zip', 'exact/output/file.zip'

# Copy a folder - needed parent folders will be created as needed
copy_folder 'exact/path', 'exact/output/folder'

# Create folder, and any of the needed parent folders
create_folder 'my_folder'

# Create folder for a file, with any of the needed parent folders
create_folder_for 'some/folder/with/file.png'

File Watcher

Bobkit comes bundled with FileWatcher, and has a shortcut method to use it.

include Bobkit::Watcher

watch do |changes|
  changes do |filename, event|
    puts "#{event}: #{filename}"
    generate
  end
end

def generate
  # Your generation logic here
end

The watch command is just like Filewatcher.new([...]).watch() do |filename, event| with the exception that the array of paths to watch is optional. If none provided, we will watch all the input folders.

DannyBen / bobkit