Location: webgen / Documentation / Tutorial Language: en Feedback: Click here

Tutorial

This short tutorial shows you how to create a website with webgen.

Creating the Basic Directories

First, you need to create the basic directories. You can either do this by hand or you can let webgen do this:

  $ webgen create sample_site

webgen created the sample_site directory which holds all directories necessary for running webgen.

The create command also accepts two options: one for a website template and one for a website style:

• A website template defines a structure for your website. For example, the project template defines several pages including a features and about page.
• A website style defines the look and feel of your website. webgen comes with some predefined styles which you can use (most of them are converted open source web design styles).

You can change the website style later by using the use website_style command for webgen, for example:

  $ webgen use website_style default

Existing files may be overwritten by this command (after asking). However, this command is not able to delete previously copied website style files, so you have to remove them yourself!

Have a look at the examples sections to see demonstrations for all shipped website templates and styles!

Now you can run webgen to create your website. There are two possibilities:

• Either change into the sample_site directory and run webgen there, like this

    $ cd sample_site
    sample_site $ webgen
    

• Or you can run webgen like this

    $ webgen -d sample_site
    

Easy! webgen has parsed the src directory and has created the HTML output. However, as we did not write any content yet, there is not much to see (only the default page). So let’s do that now!

Adding Content to the Website

When using the create command, webgen does not only create the needed directories but it also provides you with some default files, you should have at least the following ones:

• src/default.template: The default template for the new website.
• src/default.css: The default css file for the new website.
• src/index.page: The index page for the root directory of the website.

The basic scaffolding is already in place, we only have to change index.page and add other page files. Just open the file index.page in your favorite text editor and change its content. After that we create a new file, hello.page, with the following content:

---
title: Sample hello page
inMenu: true
---
This is a sample page with the title "Tutorial" and it is in the menu!!!

After that, run webgen and then open output/index.html to view your website.

Then just add page files and other content to your website and let it grow!

Using Tags and Meta Information in Pages

Meta information is specified at the beginning of a page file. Have a look at the WebPage Format reference to see how that is done in detail!

We are now going to use meta information to customize our website! Open the file default.template and add this before the </body> tag:

  File last changed on {filemdate: }!

The part {filemdate: } is called a tag. Tags are implemented using plugins and they can be used to insert dynamic content when webgen is run. For example, the menu on the page is generated with the {menu: } tag! If webgen sees a tag during the processing of a page for which no tag plugin exists, it looks at the meta information of the page. If there is a meta information entry with the tag name, it uses that content instead. We will use that now!

Open the file hello.page and add the following meta information:

filemdate: 10.4.2005

so that hello.page looks like this:

---
title: Sample hello page
inMenu: true
filemdate: 10.4.2005
---
This is a sample page with the title "Tutorial" and it is in the menu!!!

Run webgen and view the output! The tag {filemdate: } got substituted by the value specified in the meta information. As we have not put any meta information in the index.page file, a warning is issued when webgen is run and no date is shown on the page!

Writing a Simple Plugin

Because we are not quite happy with our basic file modification time tag, we are going to write a simple tag plugin.

Create the file plugin/filemdate.rb with the following content:

class FileMDateTag < Tags::DefaultTag

  infos( :name => 'Custom/FileMDate',
         :summary => "Puts the modification time of the file on the page" )

  register_tag 'filemdate'

  def process_tag( tag, chain )
    return File.mtime( chain.last.node_info[:src] ).to_s
  end

end

That’s all! The new plugin gets loaded when webgen starts and it is used when the tag filemdate is encountered. We can now safely remove the filemdate meta info from the file hello.page although you can leave it there – it won’t do any harm.

Again, just run webgen and view the output!

For more information on how to write plugins have a look at the extending webgen section!

Conclusion

You have just created a simple static website using webgen. For further information on how to procede from here have a look at the plugins section and the other documentation.