webby --help
Usage: webby [options] task [task args]
-D, --describe [PATTERN] describe the tasks (matching optional PATTERN), then exit
-P, --prereqs display the tasks and dependencies, then exit
-T, --tasks [PATTERN] display the tasks (matching optional PATTERN) with descriptions, then exit
-t, --trace turn on invoke/execute tracing, enable full backtrace
common options:
-h, --help show this message
--version show version
The @webby@ program is actually a smart wrapper around "Rake":http://docs.rubyrake.org/. It is used to run the tasks that will create new pages, build the output products, and deploy the site to a server. The list of available tasks can be seen by typing the following command in a Webby site folder:
pre. webby -T
The second program, @webby-gen@, is used less often but it is no less important. This is the *generate* command, and it is used to create a new Webby site folder and files. Type @webby-gen --help@ on the command line to see how the program is used.
webby-gen --help
Usage: webby-gen [options] template site
-f, --force overwrite files that already exist
-s, --skip skip files that already exist
-u, --update update rake tasks for the site
-p, --pretend run but do not make any changes
-t, --templates list available templates
common options:
-h, --help show this message
--version show version
The Webby generate command will create a new site folder (or update an existing site folder) using files from the desired template type. Each template is a collection of files that can be used as the starting point for a Webby project. You can see the list of available templates:
pre. webby-gen --templates
h2. Working 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.
h3(#pages). Pages
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":http://www.yaml.org/spec/1.1/ 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":#filters section of this manual). The example page above will result in the following snippet of HTML code.
You can see that the value of the @title@ attribute was substituted for the ERB snippet @<%%= @page.title %>@. 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":#erbfilter 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. h4. Page 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":#erbfilter 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 h4. Page 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":#filters section of this document. h3. Layouts 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. <% graphviz :path => "images", :class => "push-0", :alt => "layout diagram" do %> digraph layout_graph { rankdir = LR; edge [fontname="Verdana", fontsize=8]; node [fontname="Verdana", fontsize=10]; page -> layout [label="rendered\ninto"]; layout -> HTML [label="results\nin"]; } <% end %> 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.Lorem Ipsum
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.
--- extension: html filter: erb ---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. h2(#filters). Filters 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! h3(#erbfilter). ERB "ERB":http://ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html 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":#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":#helpermethods are another that are discussed elsewhere in this manual.<%= @page.title %> <%%= @content %>
The title of this page is "<%%= @page.title" %>".
The title of this page is "<%= @page.title %>".
This will generate a table of contents, but not insert outline numbering into the heading tags. The full list of "TOC attributes":/rdoc/classes/Webby/Filters/Outline.html 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.). h3. BasePath 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.
$ webby rebuild BASE='http://your.website.com/path/to/your/site'
SITE.xpaths << '/html/body//img[@usemap]' SITE.base = 'http://webby.rubyforge.org'
SITE.tidy_options = '-indent -wrap 80'