Webby ☯ Manual

1Introduction

Webby was created out of the need for a simple way to build and manage small websites. The desire was for a system that could take files written in plain text, combine them with a layout file and produce web pages. In this system, a single page can be written quickly without the need for HTML markup; the look and feel of the entire site can be changed by modifying the site layout file.

The diagram above shows the basic concept of how Webby works. Changing the layout file will result in changes to every generated HTML file. Changes to a single page will result in changes only to the HTML file corresponding to that particular page.

Webby does not limit the output to HTML. Webby can be used to generate XML files for RSS or Atom news feeds, CSS files for styling web pages, or any other type of text file that you can think of.

1.1Requirements

Webby is written in the Ruby programming language. To install and run Webby you will need the following applications installed on your system:

• Ruby
• RubyGems

1.2Installation

Webby is easily installed as a Ruby gem. From a command prompt type in the following:

sudo gem install -y webby

This will install Webby and all its required dependencies.

For those users installing Webby on the Windows platform, please omit the sudo portion of the above command. You will also need to specify the mswin32 versions of the mongrel and hpricot gems when prompted.

To make use of all the features Webby has to offer, the following gems should also be installed. These gems provide different ways to transform text into HTML or CSS.

sudo gem install -y RedCloth
sudo gem install -y BlueCloth
sudo gem install -y haml
sudo gem install -y coderay
sudo gem install -y ultraviolet

Webby can also use a few other programs to clean up generated HTML and to created pretty graphs and pictures. Where external programs are required, they will be duly noted in the manual.

1.3Running Webby

When the Webby gem is installed it also installs a webby executable program. This program is used to create a new website and to update the associated rake tasks when a new version of Webby is released. Typing in webby --help will show you the options this program supports. After you create a website, though, the webby command will not be needed.

$ webby --help

Usage: webby [options] site

    -u, --update                     update the rake tasks for the site

common options:
    -h, --help                       show this message
        --version                    show version

The day to day tasks of working with a webiste – creating pages, building the website, deploying changes to the server – are handled by the Rake application, a Ruby version of the more famous make program. Several rake tasks are provided by default. You are free to create others to make developing and deploying your website easier. To see the current list of rake tasks type in rake -T.

$ rake -T

rake autobuild          # Continuously build the website
rake build              # Build the website
rake clobber            # Delete the website
rake create:page        # Create a new page
rake create:partial     # Create a new partial
rake deploy             # deploy the website to Rubyforge
rake deploy:rsync       # Deploy to the server using rsync
rake deploy:ssh         # Deploy to the server using ssh
rake growl              # Send log events to Growl (Mac OS X only)
rake heel:start         # Start the heel server to view website (not for Windows)
rake heel:stop          # Stop the heel server
rake rebuild            # Rebuild the website
rake validate           # Alias to validate:internal
rake validate:external  # Validate hyperlinks (include external sites)
rake validate:internal  # Validate hyperlinks (exclude exteranl sites)

2Working With Resources

A resource is any file that is found in the content or layouts folders. Resources are either copied to the output folder or they are processed through the Webby filter engine to generate an output file. Resources fall into one of three types:

• Files
• Pages
• Layouts

Files are the simplest resource to handle. They are copied, unchanged, from the content folder to the output folder. Files include resources such as images, CSS stylesheets, and so forth. A file will be copied from its location in the content folder to its corresponding location in the output folder—i.e. a file located at content/some/folder/image.jpg would be copied to output/some/folder/image.jpg.

Files will only be found in the content folder. The layouts folder is reserved solely for layouts.

2.1Pages

Pages are found in the content folder along with regular files. Pages contain meta-data at the top of the file; this is what differentiates a page from a regular file. The meta-data is a section of YAML formatted text that describes various properties and attributes of the page. These attributes are used by Webby to determine how the page will be processed by the filter engine.

Let’s look at an example page.

---
title:      Lorem Ipsum
created_at: Wed Aug 29 08:57:00 -0600 2007
filter:
  - erb
  - textile
---
h2. <%= @page.title %>

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Nunc congue ipsum
vestibulum libero. Aenean vitae justo. Nam eget tellus. Etiam convallis, est eu
lobortis mattis, lectus tellus tempus felis, a ultricies erat ipsum at metus.

The page meta-data is contained in the first section — it is located between the two --- lines. The page meta-data will not be present in the generated HTML file. Only the page content (the text below the second --- line) will be rendered into the final HTML file. The meta-data defines a collection of attributes that (1) are made available to the various Webby filters and (2) provide instructions to the Webby filter engine itself.

Three attributes are defined in the above example: title, created_at, and filter. The first attribute, title, is associated with the value “Lorem Ipsum”. This attribute is used in the first line of the page content to render the title using a combination of the ERB and Textile filters (more can be read in the Filters section of this manual). The example page above will result in the following snippet of HTML code.

<h2>Lorem Ipsum</h2>

<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Nunc congue ipsum
vestibulum libero. Aenean vitae justo. Nam eget tellus. Etiam convallis, est eu
lobortis mattis, lectus tellus tempus felis, a ultricies erat ipsum at metus.</p>

You can see that the value of the title attribute was substituted for the ERB snippet Manual. All page attributes can be accessed using the @page.attribute syntax within an ERB block. This will be discussed in greater detail in the ERB Filter section.

The last attribute in the meta-data section is the filter attribute. The value for this attribute is a list of filters that will be applied to the page contents. The filters will be applied in the order they are specified. For the example page this would be the ERB filter followed by the Textile filter.

2.1.1Page Attributes

Attribute identifiers cannot contain spaces; they must be separated from their values by a colon. Other than that, you are free to define as many attributes as you like. Aside from defining values that can be rendered into a page, attributes are also used to find other pages in the site. Finding and linking to other pages is discussed in the ERB Filter section.

There are a few attributes that control when, where, and how pages are rendered. These are listed below with a brief description of how the attribute affects the system.

• destination — Defines the path in the output directory where the rendered page should be stored.
• dirty — The dirty flag is used to determine whether the page should rendered or not. Normally this is automatically determined by the filter engine, but it can be overridden by setting this attribute. If the dirty flag is set to true then the page will always be rendered. If the dirty flag is set to false then the page will never be rendered.
• extension — Defines the extension that will be appended to the filename of the rendered page in the output folder. The extension is determined by looking at the following:
  • the meta-data of the current page for an extension attribute
  • the meta-data of layout file of the current page for an extension attribute
  • the extension of this page file in the content folder
• filter — Defines the list of filters that will be applied to the contents of this page. If left blank, then the default filter will be applied to the page contents.
• layout — Defines the layout that the page contents will be rendered into. The default layout will be used if this attribute is not defined. The value of nil should be specified if the page should not be rendered into any layout.

The following attributes are defined for each page in the content folder. These attributes cannot be changed in the page’s meta-data section. However, they are available to the ERB filter when rendering the contents of a page.

• path — The full path to the file in the content folder
• dir — The relative directory in the output folder where the page will be rendered
• filename — The name of the file in the content folder excluding any path information
• ext — The extension of the file in the content folder
• mtime — The modification time of the file in the content folder
• number — Reserved variable used for multi-page content
• url — A URL suitable for creating a link to the page
• render — Returns the contents of the page as rendered by the Webby filter engine

2.1.2Page Filters

Filters operate on the content of a page by transforming the text of the content section according to the rules of the individual filter. Some filters transform simplified markup into true HTML syntax; examples of these are the Textile filter and the Markdown filter. Other filters will rewrite URLs (basepath filter) or clean up the generated HTML (tidy filter). All the filters are discussed in detail in the Filters section of this document.

2.2Layouts

Layouts provide the basic framework for a page — the header, the footer, the navigation. They provide a consistent look and feel across all pages in the website. Individual pages contain just the content for that particular page.

The diagram to the right shows a typical page rendering process. The content of a page is rendered by the Webby filter engine. The rendered content is inserted into the layout specified by the page; the content insertion occurs as the layout is being rendered. The result is the HTML that is stored in the output folder.

Layouts are treated exactly as pages are treated with one exception — the layout has access to the rendered contents of another page in site. The content of the page being rendered is made available to the layout via the @content variable accessible from the ERB filter.

---
extension: html
filter:    erb
---
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en-us">
<head>
  <title>Manual</title>
</head>
<body>
  <%= @content %>
</body>
</html>

The example above shows a very simple layout. The content for the current page being rendered will be inserted between the HTML body tags.

Along with the @content variable, all the attributes of the current page being rendered are also accessible in the layout. The page title is inserted into the HTML title tags. But again, any page attribute can be accessed within the layout via the @page variable.

3Filters

Filters are used in Webby to transform the text of pages and layouts. The filters applied to a page are defined in the meta-data of the page. The filters are used to transform different parts of the page contents resulting in HTML syntax, images, highlighted code, etc. Filters apply equally to pages and to layouts — that is, pages and layouts are treated in the same manner by filters.

This section will look at the various filters provided by Webby, what those filters do, and how they should be used. Enjoy!

3.1ERB

ERB provides an easy to use but powerful templating system for Ruby. Using ERB, Ruby code can be added to any plain text document for the purposes of generating document information details and/or flow control. Much of the functionality Webby has to offer is made available through the erb filter. ERB does not place any limitations on the content of the page, so it is recommended to use the erb filter with another filter that simplifies the HTML markup — Textile is my favorite, but Markdown and HAML support are provided in Webby, as well. Chose the markup language that suits your style.

Some examples of ERB have already been seen in the pages section of this document. Ruby code is placed between ERB delimiters, <%= ruby code %> somewhere in the content section of your page or layout. The erb filter executes that code and inserts the results into the page. Webby provides quite a few features that are accessed via ERB. Page attributes are one feature, and helper methods are another that are discussed elsewhere in this manual.

The title of this page is "<%= @page.title" %>".

The title of this page is "Manual".

3.2Textile

Textile is a lightweight markup language originally developed by Dean Allen and billed as a “humane Web text generator”. The textile filter converts Textile formatted text into valid, well-formed XHTML.

A complete textile reference is beyond the scope of this document. Please refer to the Textile reference compiled by why the luck stiff ¹.

The textile filter will operate on all the contents of a page or layout. Given that fact, it should be one of the last filters applied to the page. You can prevent a section of the page from being processed by the textile filter by surrounding it with <notextile>...</notextile> tags.

¹ Please don’t ask. Why is very smart, he wrote the Ruby code that handles Textile markup, and the code is very solid. Enjoy the benefits of his work.

3.3Markdown

Markdown is a lightweight markup language created by John Gruber. It allows you to write using an easy-to-read, easy-to-write plain text format. From the Markdown web page:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

The markdown filter will operate on all the contents of a page or layout. Given that fact, it should be one of the last filters applied to the page.

3.4HAML & SASS

HAML is a markup language created by Hampton Catlin that’s used to cleanly and simply describe the XHTML of any web document without the use of inline code. SASS is the equivalent for CSS documents. From the HAML website:

HAML and SASS are templating engines for the two most common types of documents on the web: HTML and CSS, respectively. They are designed to make it both easier and more pleasant to code HTML and CSS documents, by eliminating redundancy, reflecting the underlying structure that the document represents, and providing elegant, easily understandable, and powerful syntax.

Both the haml and the sass filter will operate on all the contents of a page or layout. Given that fact, these should be one of the last filters applied to the page.

3.5Outline

The Outline filter is used to insert outline numbering into HTML heading tags (h1, h2, h3, etc.) and to generate a table of contents based on the heading tags. The table of contents is inserted into the page at the location of the <toc /> tag. If there is no <toc /> tag, then a table of contents will not be created but outline numbering will still take place.

If a table of contents is desired without outline numbers being inserted into the heading tags, this can be specified in the attibutes of the <toc /> tag itself.

<toc numbering="off" />

This will generate a table of contents, but not insert outline numbering into the heading tags. The full list of TOC attributes can be found in the source documentation.

The Outline filter will only work on valid HTML or XHTML pages. Therefore it should be used after any markup langauge filters (textile, markdown, etc.).

3.6BasePath

The basepath filter is used to rewrite the base path location for all URLs in a page. This is useful for the times when the publish location of the website is no at the root of the web server — http://your.website.com/path/to/your/site for example. This allows pages and resources (images, javascript, stylesheets, etc.) to be referenced from the root of the Webby web server for easy development, but the paths of these resources can easily be changed by the basepath filter when the website is being deployed.

The basepath filter only works on HTML/XHTML text, and therefore, it should be one of the last (if not the last) filter applied to your content. It is recommended to only include the basepath filter in your layout(s). The basepath filter should appear before the tidy filter.

$ rake rebuild BASE='http://your.website.com/path/to/your/site'

SITE.xpaths << '/html/body//img[@usemap]'
SITE.base = 'http://webby.rubyforge.org'

3.7Tidy

Tidy is a useful application for cleaning up and detecting errors in XHTML text. The tidy filter will run your XHTML code through the tidy program and report any errors in the build log. From the HTML Tidy website:

When editing HTML it’s easy to make mistakes. Wouldn’t it be nice if there was a simple way to fix these mistakes automatically and tidy up sloppy editing into nicely layed out markup? Well now there is! Dave Raggett’s HTML TIDY is a free utility for doing just that. Tidy is able to fix up a wide range of problems and to bring to your attention things that you need to work on yourself. Each item found is listed with the line number and column so that you can see where the problem lies in your markup. Tidy won’t generate a cleaned up version when there are problems that it can’t be sure of how to handle. These are logged as “errors” rather than “warnings”.

The tidy program only works on HTML/XHTML text, and therefore, tidy should be one of the last (if not the last) filter applied to your content. It is recommended to only include the tidy filter in your layout(s).

SITE.tidy_options = '-indent -wrap 80'

4Using Rake