README.md in flutterby-0.0.21 vs README.md in flutterby-0.0.22
- old
+ new
@@ -1,50 +1,103 @@
[](https://badge.fury.io/rb/flutterby) [](https://travis-ci.org/hmans/flutterby) 
# Flutterby
-### A currently highly experimental static site generator. Yes, there are many like it; but this one is mine. (Actually, there are none like it. Ha! I'm very serious about the _experimental_ bit, though. Use with care, if at all!)
+#### A very good static site generator.
-## Example
+### Key Features
-Even though Flutterby is still very much in flux, I'm already building a bunch of sites with it; one of them is [my blog](http://hmans.io/), the source code for which you can find [here](https://github.com/hmans/hmans_me).
+- Generate a static website from a source directory!
+- Apply any number of transformations on files!
+- Built-in support for Markdown, Sass, Erb, Slim and more!
+- Extremely easy to extend with new transformation filters!
+- Sprinkle your site with Ruby code that can interact with your site's pages and data!
-## Actual Features
+## Installation & Basic Usage
-- Build your site simply as a tree of files and folders. Each file will be converted according to its extension chain (eg. `styles.css.scss` will be rendered as `styles.css`, `about.html.md` as `about.html` and so on.)
-- Built-in support for Markdown (by way of [Slodown](https://github.com/hmans/slodown)), [Sass](https://github.com/sass/sass), [ERB](http://ruby-doc.org/stdlib-2.4.0/libdoc/erb/rdoc/ERB.html) and [Slim](http://slim-lang.com/).
-- A (slow) HTTP server to serve your site dynamically (for development.)
-- Dynamically enhance your site's functionality with Ruby code.
+Flutterby is distributed as a RubyGem, so let's install it first:
+ gem install flutterby
-## Missing (but Planned) Features
+Now let's create a new project:
-- Extract filters (like Slim, Sass etc.) to separate gems
+ flutterby new mysite
+ cd mysite
+
+Now let's generate that static site:
+
+ flutterby build
+
+Or run a local development server for faster development:
+
+ flutterby server
+
+**Note**: by default, both the `build` and `server` commands assume `./site/` to be the source directory and `./_build/` to be the export directory. Please refer to `flutterby help` to see how you can override these.
+
+
+## Examples
+
+Please refer to the [Sites built with Flutterby](https://github.com/hmans/flutterby/wiki/Sites-built-with-Flutterby) page on the Flutterby Wiki for some examples.
+
+
+## Roadmap
+
+Flutterby is young, but already quite functional. Here's a list of changes I'm intending to make in the near future -- if you want to work on one of these, let me know!
+
+- Improve the template site (`flutterby new`)
+- Change `flutterby server` so it doesn't always regenerate the _entire_ site graph when a file is modified
+- Extract filters (like Slim, Sass etc.) to separate gems, to make the core gem more light-weight
- Produce a fun screencast to explain what the heck is going on here!
-- More tests, of course!
+- Write even more tests
-## How does Flutterby work?
-A loose collection of notes on how Flutterby actually generates your site -- mostly intended as rubberducking with myself.
+## Notes
-- Flutterby reads a _source directory_ and writes a static website into a _target directory_. (It can also serve a live version of your site.)
-- Before it writes (or serves) anything, it reads the entire contents from the source directory into a graph of plain old Ruby objects. Each of these objects represents a file (or folder) from your site.
-- Flutterby then walks this tree to write the resulting static site, optionally _applying filters_ first. For example, `index.html.md` will be exported as `index.html` after applying a Markdown filter.
-- These filters can be anything that modifies the Ruby object. Some examples:
- - Rendering Markdown to HTML
- - Parsing and executing ERB, Slim, HAML and other templating engines
- - Processing Sass, CoffeeScript and the likes
- - Leaving the current body intact, but modifying file attributes like the generated file's extension
-- Filters can be chained at any length you require.
-- Ruby code embedded in ERB, Slim etc. templates can interact with this object graph to do funky stuff like:
- - including the rendered contents of another object (ie. partials)
- - query the graph for certain objects (eg. "all objects in `/posts` that have `published_at` set")
- - and much more, I guess!
-- When a `_layout` object is available in the same folder as the rendered object, it will be used to wrap the object's rendered output. These layout files stack, so you can have a `/posts/_layout.erb` with the layout for a single post, and a `/_layout.erb` with the layout of your site.
-- When a `_view.rb` object is available in the same folder as the rendered object, it will be evaluated against the current view, allowing you to define your own view helpers. Like layouts, these will stack.
-- Files and folders starting with underscores (eg. `_header.html`) will never be exported.
+### How does Flutterby work?
+
+#### The Basics:
+
+Flutterby reads a _source directory_ and writes a static website into a _target directory_. (It can also serve a live version of your site.)
+
+Before it writes (or serves) anything, it reads the entire contents from the source directory into a graph of plain old Ruby objects. Each of these objects represents a file (or folder) from your site.
+
+Flutterby then walks this tree to write the resulting static site, optionally _applying filters_ first. For example, `index.html.md` will be exported as `index.html` after applying a Markdown filter.
+
+These filters can be anything that modifies the Ruby object. Some examples:
+
+- Rendering Markdown to HTML
+- Parsing and executing ERB, Slim, HAML and other templating engines
+- Processing Sass, CoffeeScript and the likes
+- Leaving the current body intact, but modifying file attributes like the generated file's extension
+
+Filters can be chained at any length you require.
+
+Files and folders starting with underscores (eg. `_secret.html`) will never be exported. There's a number of special files that start with this underscore -- more on that later.
+
+#### Using Ruby in templates:
+
+Ruby code embedded in ERB, Slim etc. templates can interact with this object graph to do funky stuff like:
+
+- including the rendered contents of another object (ie. partials)
+- query the graph for certain objects (eg. "all objects in `/posts` that have `published_at` set")
+- and much more, I guess!
+
+#### Layout files:
+
+When a `_layout` file is available in the same folder as the rendered page, it will be used to wrap the object's rendered output. These layout files stack, so you can have a `/posts/_layout.erb` with the layout for a single post, and a `/_layout.erb` with the layout of your site.
+
+#### Extending views:
+
+When a `_view.rb` file is available in the same folder as the rendered page, it will be evaluated against the current view object, allowing you to define your own view helpers. Like layouts, these will stack.
+
+#### Writing Ruby nodes:
+
+When a file has a `.rb` filter extension, the contained Ruby code will be evaluated against the Node instance. This allows you to build Ruby-based nodes. These nodes can do some powerful things, like creating other "virtual" nodes on the fly. I'm using this technique for the [archives on my blog](https://github.com/hmans/hmans_me/tree/master/site/archive).
+
+When a file named `_node.rb` is present, the contained code will be evaluated against _all_ nodes in the same directory. This allows you to easily extend multiple nodes with functionality. [I'm using this in the template project](https://github.com/hmans/flutterby/tree/master/lib/templates/new_project/site/blog) to add `#title` and `#date` methods to blog posts.
+
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).