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...
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.
webgen
CommandThe executable for webgen is called… webgen 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):
File/CopyHandler: paths: ["**/*.css", "**/*.js", "**/*.jpg", "**/*.png", "**/*.gif", "**/*.zip"] File/PageHandler: validator: xmllint Misc/SmileyReplacer: 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!
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!
Now that you know the basics, you can go on to the tutorial to create your first website with webgen!