--- title: Tutorial created_at: Tue Aug 21 17:02:40 -0600 2007 filter: textile --- h2. Require Webby has a family of friends that help it get it's job done. The command-line is where Webby lives and works. You should be comfortable with your terminal if you're going to get serious with Webby. Webby is built on top of "Ruby":http://www.ruby-lang.org/, and many of the templates use Ruby in one way or another. Learning a little bit about Ruby will make Webby far less intimidating. This tutorial requires *Ruby* to be installed as well as *Webby* and the "*RedCloth*":http://whytheluckystiff.net/ruby/redcloth/ templating engine. RedCloth provides support for the Textile markup language. h2. Create a Site You need a catchy name for your website to survive in this Web 2.0 world. Webby is distinctly Web 1.0 (or maybe Web 0.5) so we'll use the name *my_site*. 
webby my_site
This command creates a new folder named _my_site_, and the new Webby based website resides there. Change directories to the _my_site_ folder and do a listing. You will see the following files and folder: 
Rakefile
content/
layouts/
lib/
output/
rakelib/
templates/
h2. Build Your Site What? Didn't we just do that? Webby creates a site template - the larval form of your new website. "Rake":http://docs.rubyrake.org/ (another command line tool) is used to generate the HTML files for your site - a unique, beautiful butterfly. 
rake
Again, you will see lots of output scrolling across the screen. This is the rake task copying files from the _content_ folder to the _output_ folder. Some files are copied "as is", while others are compiled into HTML using your markup language of choice. Point your web browser to *my_site/output/index.html* to see what your new website looks like. h2. Making Changes Of course _Lorem Ipsum_ is some great content, but if everyone posted their site in such a state the web would be a monochromatic smurf blue. Let's change that into something more creative, more us. Open the *content/index.rhtml* file in your favorite editor. 
--- 
title:  Home Page
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.

h2. Litora Sociis
...
This is not the entire contents of the file, just to enough to get a feel for how Webby operates. The text between the dashed lines "@---@" is information about the page, referred to as _meta-data_. Obviously one piece of information is the *title* of the page, "Home Page". The other is a little more cryptic and bears some explaining. The content of this page is not HTML, but it ends up that way. How? Webby uses _filters_ on the page to transform the text into HTML. The *filter* item in the meta-data tells Webby which filters to apply to the page. Two filters will be applied, "erb" and "textile" - in that order. Each filter operates on the page text (everything after the meta-data). The erb filter (erb stands for "embedded Ruby") allows Webby to process Ruby statements found in the page text and to substitute the output of those Ruby statements back into the page text. The Ruby statements appear between @<%= ruby_code %>@ delimiters. The meta-data found at the top of the page is made available through the @@page@ object. You can see from the index.rhtml file that the page title, "Home Page", will be substituted on the first line. The textile filter operates on all page text. It is a human readable markup that gets converted into HTML. For example, the line @h3. Litora Sociis@ will be converted into @

Litora Sociis

@ by the textile filter. It is a powerful markup language that simplifies web publishing. Okay, back to our regularly scheduled page changes. Go ahead and change the title of the page in the meta-data. Then run rake again. 
rake
You'll notice much less output than before. The rake task only builds those pages that you have modified. You'll also notice, after reloading the page in your browser, that the title has now changed. Play around with making changes, running rake, and seeing your changes show up in the web browser. Done? All right! Let's go on to the next section. bq. *TIP* You can simplify this whole process - modify content, rake, view in browser - by running @rake autobuild@ on the command line. This starts a build loop that compiles the content of your website as files change. All you need to do now is - modify content, view in browser. h2. Creating a Page Let's tell the world all about your new website. We'll create a new _about_ page that describes what this website is all about, who you are, and the answer to life, the universe, and everything. 
rake create:page about
The output from the command tells you that a new file has been created - @content/about.txt@. You can now edit this page, give it a title "About", and somewhere in there include _42_. h2. Change the Layout The next step is to change how the page looks. In fact, we want to change the appearance of all the pages in our website. This is easily by done by changing the website layout file in the _layouts_ folder. Open the *layouts/default.rhtml* file in your favorite editor. 
--- 
extension: html
filter:    erb
--- 




   
   <%= @page.title %>
   
...
Ahhh, I love the smell of HTML in the morning! You'll notice that the layout file has meta-data just like the content files we've been editing. The *extension* defines the filename extension that will be appended to every file generated by this layout. Just like the content files, layouts are filtered to produce valid HTML. The current page being rendered is available in the layout using the @@page@ variable. We can see in the HTML header data that the page title will be set to the value of the @@page.title@. The meta-data of the layout is not made available in the layout itself - just the meta-data of the content file being rendered. Let's change the layout by removing the sidebar from every page. Find the sidebar div @
@. Delete that div, run rake to build the website again, and take a look at the site in your browser. You'll notice that both pages have been updated since both depend upon the default layout. h2. What Now? Let your creativity run wild! You can read more about the features of Webby in the "manual":manual.html. There you'll discover how to reference layouts other than the default, how to create page templates for simplifying blog posts. Take a look at the "tips & tricks":tips_and_tricks.html for more ideas on simplifying your web development work cycle.