Documentation from http://tinytree.info/

bonsai-docs

Bonsai
======

1. Forward
----------

Bonsai builds dynamic web sites that run anywhere. Perfect for portfolios, catalogues and other image-heavy sites.

There’s no database or admin interface - just templates for the HTML, YML files for the content, and the file system defines the hierarchy. Upload the results and you’re away.

It’s not aimed at blogs or text-heavy sites, but those where simple, well-defined hierarchies are the focus.

Bonsai is designed to keep a clear separation between content and templates, following best web practices. It has been built with an emphasis on simplicity of use.


2. 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.


3. Managing pages
-----------------

Each page is stored in its own directory, it uses a .yml file to hold its textual content. That same .yml file is also used to infer the template that will be used for your page. For example, default.yml will use the default.mustache template.

content/
  index/
    default.yml
The index page will use the default.mustache template.

###PAGE VARIABLES

Pages have variables for meta information, also, the key and value pairs in the .yml file will be cast to variables.

For example: A .yml file containing the following:

    :title: "All about growing a Bonsai"
    :body: |
      A bonsai is very difficult care for...
      You will need to obtain the agilty of 
      a cat and the strength of a bear

    :skills:
      - 
        :description: "Agility"
        :animal: "Cat"
      -
        :description: "Strength"
        :animal: "Bear"

Will have variables of {{title}} and {{body}} containing strings, {{skills}} will be a hash, which can be used to iterate over to list the skills required to become a bonsai sensei.

###PRE-DEFINED META VARIABLES

You will also have access to variables that contain details about the page in context.

permalink - The full routable path to the page, eg: /about/our/services

    slug - The last chunk of a page name, this will also be HTML/URI safe

    name - A titlecased version of the slug

    parent - The direct parent page

    children - All of the non-floating pages underneath the current page

    siblings - All of the non-floating pages at the same level. Does not include ‘self’

    ancestors - Each parent up the tree - Useful for writing breadcrumbs

    navigation - Top level non-floating pages

###“MAGIC” VARIABLES

A page that contains subdirectories will receive additional variables, for example:

    content/
      index/
        default.yml
        images/
          sansei.jpg
          miaggi.jpg

The index page will have an array variable of images, it will contain a hash:

    [
      {
        :name => "sansei.jpg", 
        :path => "/index/images/sansei.jpg", 
        :disk_path => ".../bonsai-site/content/index/images/sansei.jpg"
      },
      {
        :name => "miaggi.jpg", 
        :path => "/index/images/miaggi.jpg", 
        :disk_path => ".../bonsai-site/content/index/images/miaggi.jpg"
      }
    ]

This gives you great power and flexibility - You are able to handle pages with different contexts, based on the files that they are able to use or simply iterate over the magic asset variables to render product/project/logo images.

###Further reading

To learn more about Bonsai, you can check the SOURCE OF THIS SITE or read the GOOGLE GROUP. If you find something that you feel isn’t quite right - POST AN ISSUE for discussion.