Tutorial: Creating a Basic Website

Creating the Basic Directories

webgen needs a special directory structure so that it works out of the box. Basically, you have a website directory under which the following directories are located:

  • src: The source directory in which all the source files for the website are.

  • out: This directory is created, if it does not exist, when webgen generates the HTML files. All the output files are put into this directory.

  • ext: The extension directory (optional). You can put self-written extensions into this directory so that they are used by webgen.

The directory in which these directories are in is called the website directory.

Don’t worry too much about these directories since webgen is able to create the correct directory structure for you. By running the command webgen create sample_site, the website directory sample_site is created with the default website bundles applied. You can naturally use any available bundles by passing their names to the -b option of the create command.

A website bundle defines some starting content for a website. The default bundle defines just a sample content file sothat some output can be viewed after webgen is run. All other bundles are style bundles which define the look and feel of your website. webgen comes with many predefined style bundles and nearly all of them are converted open source web design styles.

Don’t worry if you don’t like the used website style - you can easily change it later using the webgen apply command. Have a look at the Website Styles Reference to see demonstrations for all shipped website templates and styles!

Since the basic parts are now in place, you can generate the HTML files. There are two possibilities:

  • Either you change into the sample_site directory and run the command webgen.

  • Or you run webgen from any directory and specify the website directory using the -d option, for example webgen -d sample_site.

Easy! webgen has used all files in the src directory and created the HTML output in the directory out. Now you just need to open the out/index.html file to view your website! 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!

If you run webgen in verbose mode, it prints out information about the written files. Note, however, that the shown paths are the internal path names which may be different from the actual output path names!

Since webgen automatically creates relative links, you will have a fully functional website without needing a web server! This also implies that you can deploy your website to any directory on your web server and it will just work!

Adding Content

When using the create command, webgen does not only create the needed directories but it also provides you with some default files, you will normally 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 file for the root directory of the website.
  • config.yaml: The configuration file for setting configuration options.

Template files and page files are the heart of webgen. Template files are used to define a general layout for web pages and page files define the real content. Both file types are written in Webgen Page Format. Page files are normally written in a markup language like Markdown or Textile which is easier to learn and edit for non-technical persons.

The basic scaffolding is already in place. Now we only have to adapt the page file index.page and add other page files.

All page files are written using the Webgen Page Format. Basically, you have an optional meta information block at the beginning of the file and one or more content blocks. Blocks are separated by three dashes (ie. ---) on a separate line and if you want to have a meta information block you need to have a block separator line at the beginning of your file.

Open the file index.page in your favorite text editor and change its content (ie. the first content block). After that create a new file, hello.page, in the source directory with the following content:

---
title: Sample hello page
in_menu: true
---
This is a sample page with the title "{title:}" and it is in the menu!!!

We define two meta information items (namely title and in_menu) and added some content to the first content block. Run webgen again and open out/index.html to view your changes. Add page files and other content to your website and let it grow!

Adding Dynamic Content

A static website is, as the name implies, static. However, since we generate the website it is possible to add some dynamicity to it. For example, it gets very tedious to update menu links every time we add a file that should be in the menu.

Therefore webgen provides two ways to add dynamic content out of the box:

  • ERB: This term stands for “embedded ruby”. It means that you can embed ruby statements in page and templates files that get evaluated when the files are rendered.

  • webgen tags: These are a way to add dynamic content without knowing a programming language (although limiting you to the existing tags). You just state what tag you want to use and it does its job. For example, there exists a very flexible menu generation tag.

You have already encountered a webgen tag in the last section when you created the hello.page file: the {title:} part. webgen tags can generally be specified like this: {tagname: {param: value, param2: value2}}. For detailed information on tags have a look at the Webgen::ContentProcessor::Tags documentation.

Setting configuration options

webgen provides a default configuration out of the box. If you can live with that, you do not need to change any configuration option. However, most users need to change some configuration option sometime. The configuration file is called config.yaml and has to be placed directly under the website directory. It uses YAML as file format.

Have a look at the Configuration Options Reference to get an overview over all available configuration options.

Each configuration option can be set in the configuration file by specifing the configuration option name and the new value as a key/value pair. A sample configuration file looks like this:

website.lang: de
website.link_to_current_page: true