Getting Started
Nuts and Bolts

Getting Started

Downloading and Installation

Start by downloading the latest version of StaticWeb from the RubyForge website.

untar or unzip the file into a convenient directory and you are ready to start. (For the next release there will probably be a gem or rpa package.) To install su to root and run: ruby setup.rb

Creating a Sample Website

So now you have successfully downloaded and installed StaticWeb let's begin with a simple tutorial that will show you how to create your own static website in no time at all. This tutorial is just for Linux users at the moment, but I'll be expanding it for windows users once I have tested it on windows.

Create a new folder called exampleSite inside the staticweb folder:

  • cd staticweb
  • mkdir exampleSite
  • Run the staticweb-seed program to generate the default configuration files in the exampleSite directory:

  • cd exampleSite
  • staticweb-seed

  • You'll see a folder named src has been created and inside some configuration files have been generated. You will now have:
  • index.web
  • index.keyword
  • index.template
  • index.dynamic.rb
  • project.mapping
  • default.css

  • Don't worry about these files just yet, there's an in-depth explanation of each one in the Nuts and Bolts section, but let's read them after we've built the example.

    Edit the index.web file in your favourite editor and change the default text as follows:

  • nano -w index.web
  • change the default text to say: Welcome to my new StaticWeb homepage
  • Next edit the index.config file replacing the default values as follows:

  • nano -w index.config
  • SITEBANNER:StaticWeb exampleSite
  • BROWSERTITLE:exampleSite
  • COPYRIGHT:Copyright © 2004 Your Name. All rights reserved.
  • Now change directory back up a level into the exampleSite directory and run the staticweb command to generate your website:

  • cd ../.
  • staticweb

  • And voila! as if by magic an output folder appears next to the source directory and contains the html and css files from our chosen configuration.

    Change Directory into the output folder and view the index.html in your favourite browser:

  • cd output
  • konqueror index.html

  • You should see something like this:

    Adding Pages to your Example Website

    Well that wasn't too difficult was it? You only had to edit 3 configuration files and you generated a cool looking static web site!

    Let's take it a step further and add a new page to the webite. This requires editing a few more configuration files. I know it's a bit of a pain, but that's just life. To get all the flexibility I wanted I had to have a few more config files than I would have liked. Note to self: "Perhaps I can do something about that for the next release!"

    So let's start by creating a new .web page. As you have probably guessed the .web files contain the main content for the pages and end up being the name of the html files. OK, Create a new file called example_page.web in the src directory and edit as follows:

  • cd src
  • nano -w example_page.web
  • Put the following text in the file: My new example page
  • Now for the next part there is a handy shortcut. If you want to just create a new page and use the exact same template and keywords for your new page you can just run the staticwebcommand and it will amend all the configuration files based on the defaults. You will probably do this for most of the new pages you create:

  • staticweb
  • missing: test.keyword
  • Auto-creating test.keyword
  • Adding entry to project.mapping

  • Now you can skip down to the "Now you are done!" bit further down or you can edit the configuration files manually as below.

    Next we need to make an example_page.keyword file. This file contains all the keywords that exist in the corresponding .template file and the replacement values we want to swap in when we build the html pages. It's easiest to copy the index.keyword file and rename it to example_site.keyword and edit the CONTENT value to point to our example_page.web:

  • cp index.keyword example_page.keyword
  • nano -w example_page.keyword
  • CONTENT:example_page.web
  • Almost done. One last file to edit, so open up the project.mapping file. This file co-ordinated where each html page should look for different items, such as layout, content and configuration. Add a new line for the example_page.web:

  • nano -w project.mapping
  • example_page.web [TAB][TAB] index.template [TAB][TAB] index.config [TAB][TAB] example_page.keyword

  • Note currently you must have 2 tabs between each item in the project.mapping file.

    Now you are done! just change directory up a level back into exampleSite and run the staticweb command, then change directory into the output folder and fire up your browser again and take a look at index.html:

  • cd ../.
  • staticweb
  • cd output
  • konqueror index.html
  • With a bit of luck you'll see somthing like this:

    You now know how to build and add more pages to your website. But if you want to know more about what each of the files in the src directory does and how to customize the templates take a look at the Nuts and Bolts section.


    Copyright 2004 Kingsley Hendrickse. All rights reserved. -last published Sat May 21 18:01:11 BST 2005