Bonsai, How Bonsai works

Bonsai uses a set of very simple conventions to handle content and templating. Everything is managed through the filesystem. There is no database, no admin interface. It’s just you and your content.

/site-name
  - content
    - index
      default.yml
  - public
  - templates
    default.mustache
    - partials

Content

All content is stored on the file system in the “content” directory, the folder paths that you use will imply the paths used on the final web site.

For example, a page kept under content/about-us/services will have a permalink of “/about-us/services”.

For a page to be recognised, you’ll need a template-name.yml file. The “template-name” section of the file name refers to the template that will be used to render your page.

The .yml file holds the textual content for your page, you can create key/value pairs with strings, hashes or arrays. This allows for outputting text or iterating over more complex objects to write them into your template neatly.

Page order and “Floating” pages

Bonsai will order your pages within the “navigation”, “children” and “siblings” arrays by the prefix given to its parent folder. content/1.about-us will be ordered before content/2.products but don’t worry - this will be cleaned up and removed from the final permalink.

“Floating” pages are not present in the “navigation”, “children” or “siblings” arrays. This can be achieved by not prefixing the containing directory eg content/about-us/services with a digit.

Each page that you create has access to a set of predefined variables as well as its content, you can use these to build complex navigation and get access to images or downloads stored for each page.

Templates

Templates are kept in the “templates” directory. All templates are rendered using Tilt. Running the bonsai --plant generator gives you a mustache template to get you running. To use other templating languages simply use the correct file extension. For documentation about more templating, check the specific templating language documentation. (Mustache, for those who are happy with defaults)

Public

All files kept in the “public” directory will be copied into the “output” directory. Any .less files will be processed using lesscss and will be renamed to .css When you run bonsai --repot to ready your site for deployment all the .css and .js files will be minified using the YUI compressor.