broadway

Broadway

Pluggable, portable, framework-friendly static site generator. Setting the Stage for the Ruby CMS.

Usage

Install

sudo gem install broadway

Test

rake test

Structure

Everything uses relative paths from the site root.

.
|-- _config.yml
|-- _layouts
|-- _posts (generated output)
|-- _site (github's place)
|-- _source (sinatra application for development)
|   |-- files (blog files to-be published)
|   |-- posts (blog files)
|   |-- lib (sinatra helpers)
|   `-- public (sinatra public directory)
|-- shared (javascripts, css, media, etc.)
|-- index.html
|-- robots.txt (what google should ignore)
`-- sitemap.xml (google's sitemap from jekyll)

Run

If you want to use this entirely as a web server, run this at your source root:

broadway

If you want to use it inside of Sinatra or Rails, create the site manually:

site = Broadway.build!

Models

Broadway uses Site, Post, Asset, File, Link, Slug, and Configuration to solve pretty much everything for creating a fully featured site using just Textmate.

The Site

The Site is basically the static database.

• It holds a reference to all of your other models.
• It reads a _config.yml file from a directory.
• Creates File objects out of the directory tree.
• Converts Files into Posts with slugs, tags, categories, and dates if they fit the profile.
• Finds Assets from within Posts.
• And uses a DSL to build menus out of Links.

Api

site = Broadway::Site.new
# dynamic finders
site.(models) #=> array of all models
site.find_(model)_by_(property)(value) #=> first model matching property value
site.find_(models)_by_(property)(value) #=> all models matching property value
site.find_(model)(attributes) #=> first model matching attributes
site.find_(models)(attributes) #=> all models matching attributes
site.(model)_roots #=> all hierarchical models without a parent

The Post

The Post works just like the other static site generators, it is the content input.

• It has metadata (YAML header) which defines (nested) key-value attributes.
• It has a Slug based on the folder structure, title, date, and is customizable.
• It has tags defined by metadata, which can be scoped (e.g tags by "skill" vs. "favorite")
• It has categories based on the folder structure.
• It has a kind, specifying how the post should be treated (currently post or page).
• It has children if it is a page.
• It has Assets defined by metadata, if desired.
• It has a date if a) its title was formatted like yyyy-mm-dd-title.extension, or b) metadata has defined a date attribute.

Api

post = site.posts.first #=> e.g...
post.tags #=> ["ruby", "sinatra", "rails"]
post.categories #=> ["path", "to", "post"]
post.assets #=> array of Asset objects, if defined
post.file #=> associate file object, where all calculations are based
post.slug #=> slug calculation object
post.path #=> "/path/to/post"
post.url #=> "http://site.com/path/to/post"
post.kind #=> "page" or "post" (or whatever you define)
post.children #=> array of Post objects, if it's a "page"
post.title
post.data #=> access to everything in the yaml header

The Configuration

The Configuration object is defined from _config.yml in the Broadway Site root.

• Nested YAML properties
• Can be used to store arbitrary data, such as site seo stuff, author, etc.
• Accessed in views via c("path.to.attribute").

Context

There are plenty of static site generators out there: Jekyll, Webby, Nanoc, StaticMatic, Middleman, Mercury, Frank, DynamicMatic, WebGen, Pekky, Awestruct, Massimo, Toto... The problem with them is that they are completely separate frameworks from Sinatra and Rails. They're not meant to be used with either of those. It's a lot of work to integrate them.

Broadway makes Rails and Sinatra static-compatible.

Why integrate static sites with Rails and Sinatra?

• So you can write posts in Textmate.
• So you can organize your documents and still write complex app code around them.
• So you can use all the helpers the frameworks have built in.
• So you can use Haml and Sass.
• So you can make pretty blogs and still think like a programmer.
• So you can host it on Github Pages if you want.

Tools

• SeeSaw: Convert HTML to HAML, Textile/Markdown to HTML, and lots of other conversions. Useful for converting html you find on sites to Haml for learning.
• Sinatra, HAML, JQuery, Textile (cool blog). Random site I thought was cool.
• Tilt

Sinatra on Broadway

Here is a Sinatra + Broadway Example App.

Below is a description on how you might setup a Sinatra app to be themeable and run via markdown files. TODO.

Themes

Create a folder called shared/themes/my-theme-name. In there, create folders for html, touch, and flash. In the html folder, you need the following

.
|-- index.haml # home page (layout.haml is somewhere else entirely)
|-- about
|-- blog
|-- features
|-- demos
|-- download
|-- support
|-- community
|-- shared
|   |-- stylesheets
|   |-- javascripts
|   |-- images
|   `-- partials
|   	|-- _head.haml
|   	`-- _header.haml