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?

1. So you can write posts in Textmate.
2. So you can organize your documents and still write complex app code around them.
3. So you can use all the helpers the frameworks have built in.
4. So you can use Haml and Sass.
5. So you can make pretty blogs and still think like a programmer.
6. 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