webgen logo

webgen / static website generator

static website generation made easy!

Sub Menu


  • The basics pagecontains everything one needs to get going with webgen!
  • Descriptions for plugins can be found in the plugins section

Latest news

2007-12-31: Minor release with feature enhancements. More...

2007-09-08: Small bug fix release. More...

2007-06-29: Some bug fixes and one small feature enhancement. More...


Generated by webgen

The Needed Directories

webgen needs a special directory structure so that it can work correctly. Basically, you have a website directory under which the following directories have to be:

  • src: The source directory in which all the source files for the website are. The name of this directory cannot be changed!
  • output: This directory is created, if it does not exist, when webgen is run. All the output files are put into this directory. The name of this directory and its location can be customized using the parameter Core/Configuration:outDir.
  • plugin: The extension directory. You can put self-written plugins into this directory so that they can be used by webgen. All *.rb files in this directory and its subdirectories are loaded as plugins. The name of this directory can’t be customized, too!

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

The webgen Command

The executable for webgen is called… webgen smiley ;-) It uses a command style syntax (like Subversion’s svn or Rubygem’s gem commands) through the cmdparse library. To get an overview of the possible commands run

  $ webgen help

This will output something like this:

Usage: webgen [options] COMMAND [options] [COMMAND [options] ...] [args]

Available commands:
  check          Checks things like validity of the config file or the availability of optional libraries
    config         Checks the validity of the configuration and outputs the used options (=default command)
    libs           Checks the availability of optional libraries used by plugins
  create         Creates the basic directories and files for webgen.
  help           Provide help for individual commands
  run            Runs webgen, ie. generates the HTML files (=default command)
  show           Shows various information
    config         Shows information like the parameters for all or the matched plugins
    plugins        Shows the available plugins
  use            Changes the used website or gallery styles
    gallery_style  Changes the used gallery style
    website_style  Changes the used website style
  version        Show the version of the program

Global options:
    -d, --directory DIR              The website directory, if none specified, current directory is used.
    -V, --verbosity LEVEL            The verbosity level (0-3)
    -h, --help                       Show help
    -v, --version                    Show the version of the program

As you can see, webgen supports many commands, from checking the validity of the configuration and the available libraries to displaying the configuration values. However, the main command is the run command which does the actual website generation. This command uses the current working directory as website directory if none was specified via the -d option.

You can invoke a command by specifying it after the executable name. If we also think of the executable webgen as a command, then the options for a command are specified directly after the command name and before the next command or any arguments. For example, all the following command lines are valid:

  $ webgen
  $ webgen run
  $ webgen -d doc run
  $ webgen -V 0 create -t project
  $ webgen show config
  $ webgen help create
  $ webgen help show config

The commands on the first and second line do the same because of the run command being the default command. The third command specifies a global option, as does the fourth. However, the fourth also specifies a command specific option -t. The fifth command shows how nested commands are used; in this case the config command under the show command is executed. The last two commands show how the included help command works: the sixth command shows the help for the create command and the last one shows it for the nested show config command.

For more information on how the commands work have a look at the cmdparse documentation!


webgen provides a default configuration out of the box. If you can live with that, you do not need to write any configuration files. Because most people cannot, you can use your own configuration file. The configuration file has to be written in YAML and is called config.yaml. webgen assumes it to be in the website directory.

Each plugin can specify parameters which can be configured through the configuration file. You can display a list of all available parameters by running

  $ webgen show config

(This information is also provided on this website, have a look at the plugins section!)

The list shows sorted by the plugin name the current values and the default values for each parameter. Each parameter can be overridden in the configuration file by specifing the plugin name as top level key and each parameter and value as a key/value pair. Therefore a configuration file looks like this (this is the one for the webgen homepage):

  paths: ["**/*.css", "**/*.js", "**/*.jpg", "**/*.png", "**/*.gif", "**/*.zip"]

  validator: xmllint

  emoticonPack: crystal

There is a special key for file handler plugins: defaultMetaInfo. It’s value should be a hash with the default meta information for nodes created by the plugin. The value is used to update the correct part of the Core/FileHandler:defaultMetaInfo parameter if and only if no value for the Core/FileHandler:defaultMetaInfo parameter has been set in the configuration file!

File Types

webgen can handle different file types in the source directory through its plugin concept. The File plugins are used for this task.

The most important files are the page and template files as they are used to define the content and the layout of your website. Have a look at the WebPage Format documentation to see how these files look like and how they are structured. After that have a look at the documentation for the plugins File/PageHandler and File/TemplateHandler as they are responsible for handling the page and template files!

You can naturally use any other type of file in the webgen source directory. However, be aware that some files may not be processed by webgen when no file handler plugin for them exist. For example, there is currently no file handler plugin for .svg files, so those files would be ignored. If you just want to have files copied from the source to the output directory (like images or CSS files), the File/CopyHandler plugin is what you need!

From here on…

Now that you know the basics, you can go on to the tutorial to create your first website with webgen!