--- title: Configuration Option Reference in_menu: false --- # Configuration Option Reference This reference describes all available configurations that can be set via the configuration file (or, if you want to have more control, via an extension file). ## General Options * ### website.lang Specifies the default language of the website. The default language is assigned, for example, to page files for which a language is not explicitly specified. * Syntax: `LANGUAGE` where `LANGUAGE` is a ISO-639-1/2 two or three letter language code * Examples: website.lang: deu website.lang: fr * ### website.link\_to\_current\_page If this option is set to `true`, automatically generated links from a page to itself are used. Otherwise, only the title of the page is shown. * Syntax: `BOOLEAN` where `BOOLEAN` is `true` or `false` * Examples: website.link_to_current_page: false * ### website.cache Specifies the type and location of the cache. Two types are currently supported: `:file` and `:string`. The file cache type stores the cache in a file relative to the website directory. The string cache type stores the cache directly in the second part of the configuration option (this is only useful when webgen is used as a library). * Syntax: `[TYPE, LOCATION]` where `TYPE` is one of `:file` or `:string` * Examples: website.cache: [:file, my.cache] ## Commonly Used Options * ### common.sitemap.honor\_in\_menu Specifies whether the sitemap should only include nodes that have the meta information `in_menu` set. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: Sitemap with in-menu nodes: \{sitemap: {honor_in_menu: true}} * ### common.sitemap.any\_lang Specifies whether the sitemap should include nodes in any language or only those without a language or with the language of the node in which the sitemap tag is used. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: Sitemap with nodes in any language: \{sitemap: {any_lang: true}} * ### common.sitemap.used\_kinds Specifies the kind of nodes that should be used in the sitemap. This defaults to all nodes with the kind `page`. If this is set to an empty array, any kind of node is used. * Syntax: `[KIND, ...]` where `KIND` is the kind of node that should be used. * Examples: Sitemap with only asset nodes: \{sitemap: {used_kinds: [asset]}} ## Source and Output Specific Options * ### sources Specifies one or more sources from which paths are read. This can also be used, for example, to additionally add other directories as source directories that may or may not be located in the website directory. * Syntax: `[[MOUNT POINT, NAME, ARG1, ARG2, ...], ...]` where `MOUNT POINT` is the path under which the source should be mounted, `NAME` is the name of the source class (for example, `Webgen::Source::FileSystem`) and `ARG1`, `ARG2` and so on are the parameters for the source class. The supported parameters can be found in the documentation for each source class. * Examples: sources: [[/, Webgen::Source::FileSystem, src], [/, Webgen::Source::FileSystem, /mnt/pictures, **/*.jpg] * ### output Specifies the output class that should be used for writing out the generated paths. * Syntax: `[NAME, ARG1, ARG2, ...]` where `NAME` is the name of the output class (for example, `Webgen::Output::FileSystem`) and `ARG1`, `ARG2` and so on are the parameters for the output class. The supported parameters can be found in the documentation for each output class. * Examples: output: [Webgen::Output::FileSystem, custom_out] * ### sourcehandler.patterns Specifies the path patterns that are used by the individual source handlers. This configuration option is not normally set in the configuration file but in an extension file (e.g. `ext/init.rb`) because otherwise the default entries would be overwritten. * Syntax: `\{NAME: [PATTERN, PATTERN, ...], ...}` where `NAME` is the name the name of a source handler and `PATTERN` are one or more path patterns. * Examples (for `ext/init.rb`): config.sourcehandler.patterns['Webgen::SourceHandler::Copy'] << '**/*.swf' * ### sourcehandler.invoke Specifies the invocation order of the various source handlers. This configuration option should normally only be used by extensions to register their source handlers! * Syntax: `\{ORDER: [NAME, ...], ...}` where `ORDER` is a number identifying the priority of the invocation (source handlers with a lower `ORDER` setting are executed earlier than ones with a higher `ORDER` setting) and `NAME` is the name of a source handler. * Examples (for `ext/init.rb`): config.sourcehandler.invoke[5] << 'Extension::MyNewSourceHandler' * ### sourcehandler.casefold Specifies whether path names should be considered case-sensitive (set to `false`) or case-insensitive (set to `true`). * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: sourcehandler.casefold: true * ### sourcehandler.use\_hidden\_files Specifies whether hidden files (those starting with a dot) should be used. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: sourcehandler.use_hidden_files: true * ### sourcehandler.ignore Specifies path patterns that should be ignored. All paths that match at least one of the patterns are never used. * Syntax: `[PATTERN, ...]` where `PATTERN` is a valid path pattern. * Examples: sourcehandler.ignore: [**/*~, **/CVS/**] * ### sourcehandler.default\_lang\_in\_output\_path Specifies whether output paths in the default language should have the language code in their name. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: sourcehandler.default_lang_in_output_path: true * ### sourcehandler.default\_meta\_info Specifies default meta information for all source handlers or for specific ones. The configuration file provides a shortcut for setting meta information items using the special `default_meta_info` key (see the examples). * Syntax: `\{NAME: {MI_KEY: MI_VALUE, ...}, ...}` where `NAME` is either the name of a source handler or the special key `:all` which sets default meta info for all source handlers. * Examples: default_meta_info: :all: output_path_style: [:parent, :cnbase, :lang, :ext] Webgen::SourceHandler::Page: in_menu: true * ### sourcehandler.template.default\_template Specifies the name of the default template file of a directory. This template is used as fallback when no specific template is specified. * Syntax: `PATH` where `PATH` is the absolute localized canonical name of the default template. * Examples: sourcehandler.template.default_template: other.template ## Content Processor Specific Options * ### contentprocessor.map This configuration option maps short names for content processor to their class names. The short names are used, for example, in the procesing pipeline of a content block of a file in Webgen Page Format. This configuration option is normally only used by extensions to register the short name of a content processor! * Syntax: `\{SHORT: NAME, ...}` where `SHORT` is the short name of the content processor class `NAME`. * Examples (for `ext/init.rb`): config['contentprocessor.map']['newcp'] = 'Extension::MyNewContentProcessor' * ### contentprocessor.erubis.use\_pi Specifies whether Erubis should look for XML processing instructions or the standard ERB tags when processing content. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: contentprocessor.erubis.use_pi: true * ### contentprocessor.erubis.options This configuration option can be used to specify additional options that the Erubis processor should use. * Syntax: `\{KEY: VALUE, ...}` where `KEY` and `VALUE` are key-value pairs of options where `KEY` needs to be a Symbol and not a String. * Examples: contentprocessor.erubis.options: {:trim: true} * ### contentprocessor.tags.prefix Specifies the optional prefix that is used for tag names to avoid name clashes when another content processor uses similar markup. * Syntax: `PREFIX` where `PREFIX` is the prefix name. * Examples: contentprocessor.tags.prefix: webgen contentprocessor.tags.prefix: tag * ### contentprocessor.tags.map This configuration option maps short names for tag classes to tag class names. The short names are used in page and template files to specify the tag. This configuration option is normally only used by extensions to register the short name of a content processor. * Syntax: `\{SHORT: NAME, ...}` where `SHORT` is the short name of the tag class `NAME`. * Examples (for `ext/init.rb`): config['contentprocessor.tags.map']['highlight'] = 'Extension::MyHighlightingTag' ## Tag Specific Options These options are not normally set in the configuration file but given directly as options to the respective tag classes. Therefore, all examples in this section show the use of these options in files in Webgen Page Format. * ### tag.breadcrumbtrail.separator Specifies the string that should be used as separator between indivdual parts of the breadcrumb trail. * Syntax: `SEPARATOR` where `SEPARATOR` is a string (special HTML characters need to be properly escaped) * Examples: Breadcrumb trail with different separator: \{breadcrumb_trail: {separator: ' --- '}} * ### tag.breadcrumbtrail.omit\_index\_path Specifies that the last part of the breadcrumb trail should be omitted if it is an index path. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: Breadcrumb trail with index path omitted: \{breadcrumb_trail: {omit_index_path: true}} * ### tag.breadcrumbtrail.start\_level Specifies the level at which the breadcrumb trail starts. The default of 0 means to start a the root directory. Setting this option to 1 starts the breadcrumb trail at the first level. If you specify negative numbers, then everything is calculated from the end of the trail. Following is a diagram showing the level numbers for a sample path: 0 1 2 3 / dir1 / dir2 / myfile.html -4 -3 -2 -1 Be aware that the you need to take the `tag.breadcrumbtrail.omit_index_path` option into account when specifying the level number. * Syntax: `INTEGER` where `INTEGER` is any integer number * Examples: Breadcrumb trail starting at level 2: \{breadcrumb_trail: {start_level: 2}} * ### tag.breadcrumbtrail.end\_level Specifies the level at which the breadcrumb trail ends. Have a look at the documentation for `tag.breadcrumbtrail.start_level` for more information on the useable level numbers. * Syntax: `INTEGER` where `INTEGER` is any integer number * Examples: Breadcrumb trail ending at level 2: \{breadcrumb_trail: {end_level: 2}} * ### tag.coderay.lang Specifies the language that should be used for syntax highlighting. * Syntax: `LANG` where `LANG` is one of <%= (require 'coderay'; CodeRay::Scanners.list.map {|n| '`' + n + '`'}.join(', ')) %>. * Examples: highlighting some ruby code \{coderay:: ruby}puts 5 + 5{coderay} * ### tag.coderay.process\_body Specifies whether the body of the tag should be processed by the tags content processor first. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: wrapping in a span: \{coderay:: {lang: ruby, process_body: false}}puts 5 + 5{coderay} * ### tag.coderay.wrap Specifies in which HTML element the highlighted code should be wrapped. * Syntax: `WRAP` where `WRAP` is either `div` or `span` * Examples: wrapping in a span: \{coderay:: {lang: ruby, wrap: span}}puts 5 + 5{coderay} * ### tag.coderay.line\_numbers Specifies whether line numbers should be shown. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: not showing line numbers: \{coderay:: {lang: ruby, line_numbers: false}}puts 5 + 5{coderay} * ### tag.coderay.line\_number\_start Specifies the line number that should be used for the first line. * Syntax: `NUMBER` where `NUMBER` is an integer value. * Examples: starting with line 4: \{coderay:: {lang: ruby, line_number_start: 4}}puts 5 + 5{coderay} * ### tag.coderay.bold\_every Specifies the interval at which the line numbers should appear bold. * Syntax: `NUMBER` where `NUMBER` is an integer value. * Examples: every other line bold: \{coderay:: {lang: ruby, bold_every: 2}}puts 5 + 5{coderay} * ### tag.coderay.tab\_width Specifies the number of spaces that should be used to replace tabulator characters. * Syntax: `NUMBER` where `NUMBER` is an integer value. * Examples: tabulator == 4 spaces: \{coderay:: {lang: ruby, tab_width: 4}}puts 5 + 5{coderay} * ### tag.date.format Specifies the format that should be used for formatting the current date. The format string needs to be in a format supported by Ruby's method [Time#strftime](http://www.ruby-doc.org/core/classes/Time.html). * Syntax: `FORMAT` where `FORMAT` is a string. * Examples: very short date format: \{date: {format: '%Y-%m-%d'}} * ### tag.executecommand.command Specifies the command that should be executed. This option is the default mandatory option for Webgen::Tag::ExecuteCommand. * Syntax: `COMMAND` where `COMMAND` is the to-be-executed command. * Examples: executing a simple command \{exeucte_cmd: echo hallo} * ### tag.executecommand.process\_output Specifies whether the output of the executed command should be further processed by the tags content processor. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: executing command without further processing \{execute_cmd: {command: 'echo hallo', process_output: false}} * ### tag.executecommand.escape\_html Specifies whether special HTML characters in the output of the executed command should be escaped. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: executing command, output not escaped \{execute_cmd: {command: 'echo hallo', escape_html: false}} * ### tag.includefile.filename Specifies the name of the file that should be included. The filename needs to be relative to the website directory or an absolute path. This option is the default mandatory option for Webgen::Tag::IncludeFile. * Syntax: `FILENAME` where `FILENAME` is the name of a file * Examples: including a file \{include_file: my_file.txt} * ### tag.includefile.process\_output Specifies whether the content of the file should be further processed by the tags content processor. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: including a file without further processing \{include_file: {filename: my_file.txt, process_output: false}} * ### tag.includefile.escape\_html Specifies whether special HTML characters in the content of the file should be escaped. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: including a file without escaping \{include_file: {filename: my_file.txt, escape_html: false}} * ### tag.langbar.separator Specifies the string that should be used as separator between the individual language parts. * Syntax: `SEPARATOR` where `SEPARATOR` is a string (special HTML characters need to be properly escaped) * Examples: Langbar with another separator: \{langbar: {separator: ' --- '}} * ### tag.langbar.show\_own\_lang Specifies whether the link to the language of the current page should be displayed. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: Langbar with current page's lang not shown: \{langbar: {show_own_lang: false}} * ### tag.langbar.show\_single\_lang Specifies whether the list should be displayed even if there are no translations of the page (i.e. when there is only one page). * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: Langbar with single language not shown: \{langbar: {show_single_lang: false}} * ### tag.langbar.lang\_names This configuration option can be used to specify the language names that should be displayed instead of the language codes. * Syntax: `\{CODE: NAME, ...}` where `CODE` is a language code and `NAME` the associated language name of the code. * Examples: Langbar with custom language names: \{langbar: {lang_names: {de: Deutsch, en: English}}} * ### tag.menu.used\_nodes Specifies the type of nodes that should be used for menu generation. If `all` is specified then all available menu nodes are used, if `files` is specified then only menu nodes that represent files or directories are used and if `fragments` is specified then only the fragment nodes of the displayed file are used. * Syntax: `TYPE` where `TYPE` is one of `all`, `files` or `fragments` * Examples: Show the fragment node menu: \{menu: {used_nodes: fragments}} * ### tag.menu.start\_level Specifies the start level for the menu. All nodes with a lower level than this number are not shown in the menu. * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one. * Examples: Menu starting at level 2: \{menu: {start_level: 2}} * ### tag.menu.min\_levels Specifies the minimum number of levels that should always be shown. For example, if this is set to `2` then two menu levels are always shown. * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one. * Examples: Menu that always shows at least 2 levels : \{menu: {min_levels: 2}} * ### tag.menu.max\_levels Specifies the maximum number of levels that should be shown even if there would be more. For example, if this is set to `2` then there are only shown at most two menu levels. * Syntax: `LEVEL` where `LEVEL` is a number that is greater or equal to one. * Examples: Menu that always shows at most 2 levels : \{menu: {max_levels: 2}} * ### tag.menu.show\_current\_subtree\_only Specifies whether only the current subtree (ie. the subtree in which the node is that is displayed) should be shown in the menu or all subtrees. This option takes effect when there are at least two menu levels visible. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: Showing all subtrees: \{menu: {show_current_subtree_only: false}} * ### tag.menu.nested Specifies whether the generated menu should contain nested lists, ie. whether sub menus are put inline ul 1 li 2 ul 3 li 4 li 5 li 6 or separately following the previous menu level ul 1 li 2 li 6 ul 3 li 4 li 5 > When this option is enabled you should enable the option > `tag.menu.show_current_subtree_only`. Otherwise the generated menu will look a little bit > confusing. {.information} * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: Don't use nested lists: \{menu: {nested: false}} * ### tag.relocatable.path The default mandatory configuration option for Tag::Relocatable that specifies the path that should be made relocatable. This option is the default mandatory option for Webgen::Tag::Relocatable. * Syntax: `PATH` where `PATH` is a (localized) canonical name. * Examples: Some Path * ### tag.tikz.path The default mandatory configuration option for Tag::TikZ that specifies the (naturally non-existing) source path that should be used for creating the TikZ image. The output path is derived from this path the usual way. You shouldn't use a path that does already exist! * Syntax: `PATH` where `PATH` is a relative or absolute source path. * Examples: \{tikz:: images/tikz.png}\tikz \draw (0,0) -- (0,2);{tikz} * ### tag.tikz.libraries Specifies the names of additional TikZ library names that should be used when creating the image. * Syntax: `[NAME, ...]` where `NAME` is the name of a TikZ library. * Examples: \{tikz:: {path: images/tikz.png, libraries: [mindmap, arrows]}} \tikz \draw (0,0) -- (0,2) -- (2,2); {tikz} * ### tag.tikz.opts Specifies additional global options for the `tikzpicture` environment. * Syntax: `OPTS` where `OPTS` is the string with the global options. * Examples: \{tikz:: {path: images/tikz.png, opts: 'scale=3, line cap=round'}} \tikz \draw (0,0) -- (0,2) -- (2,2); {tikz} * ### tag.tikz.resolution Specifies the render and output resolutions that should be used to convert the TikZ image in PDF format to the chosen image format. The first number specifies the render resolution and the second one the output resolution. If the render resolution is higher than the output resolution, the final image quality is better but the image needs to scaled down to the output resolution. * Syntax: `RENDER_RES OUTPUT_RES` where `RENDER_RES` is the integer specifying the render resolution and `OUTPUT_RES` is the integer specifying the output resolution. * Examples: \{tikz:: {path: images/tikz.png, resolution: 300 72}} \tikz \draw (0,0) -- (0,2) -- (2,2); {tikz} * ### tag.tikz.transparent Specifies whether the generated image should be transparent. This only works when the path specified by `tag.tikz.path` option has the extension `.png`! You should probably also set the background of the generated image tag to transparent. * Syntax: `BOOLEAN` where `BOOLEAN` is either `true` or `false`. * Examples: \{tikz:: {path: images/tikz.png, transparent: true}} \tikz \draw (0,0) -- (0,2) -- (2,2); {tikz} * ### tag.tikz.img\_attr Specifies additional HTML attributes that should be set on the generated `img` tag. * Syntax: `\{KEY:VALUE, ...}` where `KEY` is a valid HTML `img` tag attribute name and `VALUE` the to-be-set value. * Examples: \{tikz:: {path: images/tikz.png, img_attr: {alt: Some TikZ picture}}} \tikz \draw (0,0) -- (0,2) -- (2,2); {tikz} --- ## Miscelleanous Configuration Options * ### resources A map from resource names to resource identifiers. Should only be used by extensions and not be set in the configuration file. * Syntax: `NAME` TODO # All things regarding logging config.logger.mask(nil, :doc => 'Only show logging events which match the regexp mask')