author: &author Thomas Leitner <t_leitner@gmx.at> summary: Built-in webgen extensions description: |

This is the extension bundle that comes with webgen. It provides the
core extensions and a handful of generally useful extensions.

extensions:

bundle_infos:
  author: *author
  summary: Provides access to information about bundles and their ressources like extensions and options

cli:
  author: *author
  summary: Provides access to the command parser instance for adding CLI commands

content_processor:
  author: *author
  summary: Provides a generic framework for processing content
content_processor.blocks:
  author: *author
  summary: Replaces a special xml tag with the rendered block of a node in Webgen Page Format
content_processor.builder:
  author: *author
  summary: Allows one to programatically create valid XHTML/XML documents
content_processor.cssminify:
  author: *author
  summary: Compresses CSS files
content_processor.erb:
  author: *author
  summary: Allows one to use ERB (embedded Ruby) in the content
content_processor.erubis:
  author: *author
  summary: Allows one to use ERB (embedded Ruby) in the content (faster than the erb processor)
content_processor.fragments:
  author: *author
  summary: Generates fragment nodes from all HTML headers which have an id attribute set
content_processor.haml:
  author: *author
  summary: Allows one to write HTML with the Haml markup language
content_processor.html_head:
  author: *author
  summary: Inserts various HTML tags like links to CSS/Javascript files into the HTML head tag
content_processor.kramdown:
  author: *author
  summary: Fast superset-of-Markdown to HTML converter
content_processor.maruku:
  author: *author
  summary: Converts content written in a superset of Markdown to HTML
content_processor.rainpress:
  author: *author
  summary: Compresses CSS files
content_processor.rdiscount:
  author: *author
  summary: Converts content written in Markdown to HTML
content_processor.rdoc:
  author: *author
  summary: Converts content written in RDoc markup to HTML
content_processor.redcloth:
  author: *author
  summary: Converts content written in Textile markup to HTML
content_processor.ruby:
  author: *author
  summary: Generate arbitrary output using plain Ruby
content_processor.sass:
  author: *author
  summary: Converts content written in the Sass meta language to valid CSS
content_processor.scss:
  author: *author
  summary: Converts content written in the Sassy CSS language to valid CSS
content_processor.tags:
  author: *author
  summary: Provides a very easy way for adding dynamic content
content_processor.tidy:
  author: *author
  summary: Uses the tidy program to convert the content into valid (X)HTML
content_processor.tikz:
  author: *author
  summary: Converts the content (LaTeX TikZ picture commands) into an image
content_processor.xmllint:
  author: *author
  summary: Uses the xmllint program to check the content for well-formedness and/or validness

context_modules:
  author: *author
  summary: Allows adding helper methods (defined in modules) to the Context object

destination:
  author: *author
  summary: Provides an extendable way for writing the generated files
destination.file_system:
  author: *author
  summary: Writes the generated content to a specified directory

item_tracker:
  author: *author
  summary: Tracks items for nodes which allows webgen to check if a node has changed
item_tracker.node_content:
  author: *author
  summary: Tracks changes to the content of a node
item_tracker.node_meta_info:
  author: *author
  summary: Tracks changes to the meta information of a node
item_tracker.nodes:
  author: *author
  summary: Tracks changes to a (nested) list of nodes
item_tracker.file:
  author: *author
  summary: Tracks changes to a file
item_tracker.missing_node:
  author: *author
  summary: Tracks missing nodes via their expected alcn/acn/dest_path
item_tracker.template_chain:
  author: *author
  summary: Tracks the template chain of a node

link_definitions:
  author: *author
  summary: Provides an easy way to provide globally shared link definitions (used, for example, by the content processor kramdown)

misc:
  author: *author
  summary: Namespace for miscellaneous extensions
misc.dummy_index:
  author: *author
  summary: Creates dummy index destination paths for directories that don't have any

node_finder:
  author: *author
  summary: Generic node finding extension, allows adding of custom filters

path_handler:
  author: *author
  summary: Provides an extendable way to create nodes from source paths.
path_handler.directory:
  author: *author
  summary: Creates the needed output directories from the source directories
path_handler.meta_info:
  author: *author
  summary: Provides the ability to set meta information for any path or node
path_handler.template:
  author: *author
  summary: Handles template files for layouting page and other template files
path_handler.page:
  author: *author
  summary: Generates HTML files from page files
path_handler.copy:
  author: *author
  summary: |
    Copies files from the source to the destination directory, optionally processing
    them with one or more content processors
path_handler.feed:
  author: *author
  summary: Automatically generates atom or RSS feeds for a set of files
path_handler.sitemap:
  author: *author
  summary: Generates a sitemap file
path_handler.virtual:
  author: *author
  summary: Creates nodes for additional, virtual paths
path_handler.api:
  author: *author
  summary: Creates Ruby API documentation pages via RDoc

sass_load_paths:
  author: *author
  summary: Allows adding custom Sass load paths

source:
  author: *author
  summary: Provides an extendable way for finding source paths
source.file_system:
  author: *author
  summary: Provides paths under a specified directory that match a certain pattern
source.stacked:
  author: *author
  summary: Allows combining multiple sources into one
source.tar_archive:
  author: *author
  summary: Provides paths from a specified (gzipped) tar archive that match a certain pattern

tag:
  author: *author
  summary: Handles webgen tags (an easy way for adding dynamic content)
tag.date:
  author: *author
  summary: Displays the current date/time in a customizable format
tag.meta_info:
  author: *author
  summary: Outputs the value of a given meta information key of the generated page
tag.relocatable:
  author: *author
  summary: Makes the given path relative to the generated page
tag.link:
  author: *author
  summary: Creates a link to a given path
tag.execute_command:
  author: *author
  summary: Includes the output of a command
tag.include_file:
  author: *author
  summary: Includes the content of a file
tag.coderay:
  author: *author
  summary: Applies syntax highlighting to the tag body
tag.tikz:
  author: *author
  summary: Generates an output image from the specified TikZ commands
tag.langbar:
  author: *author
  summary: Displays a list of links to translations of the content page
tag.breadcrumb_trail:
  author: *author
  summary: Creates a breadcrumb trail (i.e. shows the directory hierarchy) for the content page
tag.menu:
  author: *author
  summary: Creates a customizable menu

task:
  author: *author
  summary: |
    Provides a standard interface for working with tasks that perform actions like creating a
    website or generating it.
task.create_bundle:
  author: *author
  summary: Creates an extension bundle, either for local use or for distribution via Rubygems
task.create_website:
  author: *author
  summary: Creates a webgen website, optionally using a template
task.generate_website:
  author: *author
  summary: Generates the website

options:

content_processor.erb.trim_mode:
  summary: |
    The ERB trim mode. The string can contain any combination of '%', '<' and '<>' -- see the API
    documentation of ERB for more information.
  syntax: |
    `STRING` where `STRING` is any combination of any combination of '%', '<' and '<>'
  example:
    config: |
      content_processor.erb.trim_mode: '%<'

content_processor.erubis.options:
  summary: |
    Additional Erubis options. Have a look at the Erubis documentation for available options.
  syntax: |
    `{KEY: VALUE, ...}` where `KEY` and `VALUE` are key-value pairs of options
  example:
    config: |
      content_processor.erubis.options: {trim: true}

content_processor.erubis.use_pi:
  summary: |
    Specifies whether Erubis should look for XML processing instructions or the standard ERB tags
    when processing content.
  syntax: |
    `true` or `false`
  example:
    config: |
      content_processor.erubis.use_pi: true

content_processor.kramdown.handle_links:
  summary: |
    Specifies whether all links in a kramdown document should be processed by webgen. If this
    option is set, all links are automatically resolved using webgen's built-in facilities. This
    saves some typing and makes the document more robust since all links are automatically checked
    and warnings displayed if the link target is not found.
  syntax: |
    `true` or `false`
  example:
    config: |
      content_processor.kramdown.handle_links: false

content_processor.kramdown.ignore_unknown_fragments:
  summary: |
    Specifies whether unknown, non-resolvable fragment parts should be ignored. This is useful
    when there are links to fragments that have no internal representation.
  syntax: |
    `true` or `false`
  example:
    config: |
      content_processor.kramdown.ignore_unknown_fragments: true

content_processor.kramdown.options:
  summary: |
    Additional options for the kramdown processor. Have a look at the kramdown documentation for
    available options.
  syntax: |
    `{KEY: VALUE, ...}` where `KEY` and `VALUE` are key-value pairs of kramdown options
  example:
    config: |
      content_processor.kramdown.options: {auto_ids: false, coderay_line_numbers: null}

content_processor.rainpress.options:
  summary: |
    Options for the rainpress CSS compressor. All rainpress options are enabled by default, so
    this can be used to disable some compression methods.
  syntax: |
    `{KEY: false, ...}` where `KEY` are valid rainpress option keys
  example:
    config: |
      content_processor.rainpress.options: {comments: false}

content_processor.redcloth.hard_breaks:
  summary: |
    Specifies whether hard breaks (i.e. single newlines) in paragraphs are converted to HTML break
    tags.
  syntax: |
    `true` or `false`
  example:
    config: |
      content_processor.redcloth.hard_breaks: true

content_processor.sass.options:
  summary: |
    Additional Sass options (also used by the scss content processors). Have a look at the Sass
    documentation for available options.
  syntax: |
    `{KEY: VALUE, ...}` where `KEY` and `VALUE` are key-value pairs of Sass options
  example:
    config: |
      content_processor.sass.options: {line_numbers: true}

content_processor.tidy.options:
  summary: |
    Additional options passed to the `tidy` command (`-q` is always used).
  syntax: |
    `STRING` where `STRING` is the string with the command line options
  example:
    config: |
      content_processor.tidy.options: "-utf8"

content_processor.tikz.libraries:
  summary: |
    Array of additional TikZ library names.
  syntax: |
    `[NAME, ...]` where `NAME` is the name of a TikZ library
  example:
    config: |
      content_processor.tikz.libraries: [mindmap, arrows]
  example:
    tag: |
      {tikz:: {path: tikz.png, content_processor.tikz.libraries: [mindmap, arrows]}}
      \tikz \draw (0,0) -- (0,2) -- (2,2);
      {tikz}

content_processor.tikz.opts:
  summary: |
    A string with global options for the `tikzpicture` environment
  syntax: |
    `OPTS` where `OPTS` is the string with the global options
  example:
    config: |
      content_processor.tikz.opts: 'scale=3, line cap=round'
    tag: |
      {tikz:: {path: tikz.png, content_processor.tikz.opts: 'scale=3, line cap=round'}}
      \tikz \draw (0,0) -- (0,2) -- (2,2);
      {tikz}

content_processor.tikz.resolution:
  summary: |
    The render and output resolutions that should be used for converting the TikZ image in PDF
    format to the chosen image format. The first number specifies the render resolution and the
    second the output resolution. If the render resolution is higher than the output resolution,
    the final image quality is better by scaling the image down to the output resolution.
  syntax: |
    `RENDER OUTPUT` where `RENDER` is the integer specifying the render resolution and `OUTPUT` is
    the integer specifying the output resolution.
  example:
    config: |
      content_processor.tikz.resolution: 300 72
    tag: |
      {tikz:: {path: tikz.png, content_processor.tikz.resolution: 300 72}}
      \tikz \draw (0,0) -- (0,2) -- (2,2);
      {tikz}

content_processor.tikz.template:
  summary: |
    The template node containing the LaTeX framework that should be used for creating the TikZ
    image.
  syntax: |
    `PATH` where `PATH` is the (a)(l)cn of a template node
  example:
    config: |
      content_processor.tikz.template: /tmpl/my_tikz.template
    tag: |
      {tikz:: {path: tikz.png, content_processor.tikz.template: /my_tikz.template}}
      \tikz \draw (0,0) -- (0,2) -- (2,2);
      {tikz}

content_processor.tikz.transparent:
  summary: |
    Specifies whether the generated image should be transparent. This configuration option is only
    used when the destination path of the TikZ image has the extension ".png"!
  syntax: |
    `true` or `false`
  example:
    config: |
      content_processor.tikz.transparent: true
    tag: |
      {tikz:: {path: tikz.png, content_processor.tikz.transparent: true}}
      \tikz \draw (0,0) -- (0,2) -- (2,2);
      {tikz}

content_processor.tikz.engine:
  summary: |
    Specifies which LaTeX engine should be used. Default is pdflatex, but you may want to use
    xelatex or lualatex if needed.
  syntax: |
    `pdflatex` or `lualatex` or `xelatex`
  example:
    config: |
      content_processor.tikz.engine: lualatex
    tag: |
      {tikz:: {path: tikz.png, content_processor.tikz.engine: xelatex}}
      \tikz \draw (0,0) -- (0,2) -- (2,2);
      {tikz}

content_processor.xmllint.options:
  summary: |
    Options passed to the `xmllint` command.
  syntax: |
    `STRING` where `STRING` is the string with the command line options.
  example:
    config: |
      content_processor.xmllint.options: "--catalogs --noout"

destination:
  summary: |
    The destination extension that should be used for writing out the generated paths.
  syntax: |
    `[NAME, ARG1, ARG2, ...]` where `NAME` is the short name of the destination extension (for
    example "file_system") and `ARG1`, `ARG2` and so on are the parameters for the destination
    extension. The supported parameters can be found in the documentation for each destination
    extension.
  example:
    config: |
      destination: [file_system, custom_out_dir]

misc.dummy_index.directory_indexes:
  summary: |
    A list of directory index names that should be recognized. These index names are used to
    determine whether a directory already has a valid directory index. The first entry is also
    used as the name for the dummy directory index that is created if needed.
  syntax: |
    `[INDEX NAME, ...]` where `INDEX NAME` is a directory index name
  example:
    config: |
      misc.dummy_index.directory_indexes: [index.html, index.htm, default.htm]

misc.dummy_index.enabled:
  summary: |
    Specifies whether dummy index paths should automatically be created.
  syntax: |
    `true` or `false`
  example:
    config: |
      misc.dummy_index.enabled: false

node_finder.option_sets:
  summary: |
    Predefined node finder option sets. This option allows one to define common node finder option
    sets beforehand and then use them for any node finder operation.
  syntax: |
    `{NAME: OPTION SET, ...}` where `NAME` is the name of the to-be-defined option set and `OPTION
    SET` is a hash with node finder options
  example:
    config: |
      node_finder.option_sets:
        menu: {in_menu: true, sort: sort_info, levels: [1,3]}
        sub_menu: {descendants: true, levels: [2,10]}

path_handler.default_template:
  summary: |
    The name of the default template of a directory. This template is used as fallback when no
    specific template is specified.
  syntax: |
    `PATH` where `PATH` is the (a)(l)cn of the default template
  example:
    config: |
      path_handler.default_template: other.template

path_handler.lang_code_in_dest_path:
  summary: |
    Specifies whether destination paths should have the language part in their name. This option
    can either be set to `true` (all paths get the language part), `false` (no path gets a
    language part) or `except_default` (all paths except those in the default language -- see the
    website.lang configuration option -- get the language part).
  syntax: |
    `true`, `false` or `except_default`
  example:
    config: |
      path_handler.lang_code_in_dest_path: true

path_handler.patterns.case_sensitive:
  summary: |
    Specifies whether path names should be considered case-sensitive (value `true`) or
    case-insensitive (value `false`).
  syntax: |
    `true` or `false`
  example:
    config: |
      path_handler.patterns.case_sensitive: true

path_handler.patterns.match_leading_dot:
  summary: |
    Specifies whether paths with a leading dot, i.e. hidden files, should be used.
  syntax: |
    `true` or `false`
  example:
    config: |
      path_handler.patterns.match_leading_dot: true

path_handler.version_in_dest_path:
  summary: |
    Specifies whether destination paths should use the version name in their name. This option can
    either be set to `true` (all paths get the version part), `false` (no path gets a version
    part) or `except_default` (all paths except those with the default version name get the
    version part).
  syntax: |
    `true`, `false` or `except_default`
  example:
    config: |
      path_handler.version_in_dest_path: true

sources:
  summary: |
    One or more source extensions from which paths are read. This can be used, for example, to
    additionally add source directories that may or may not be located in the website directory.
  syntax: |
    `[[MOUNT POINT, NAME, ARG1, ARG2, ...], ...]` where `MOUNT POINT` is the absolute path under
    which the source should be mounted, `NAME` is the short name of the source extension (for
    example, "file_system") and `ARG1`, `ARG2` and so on are the parameters for the source
    extension. The supported parameters can be found in the documentation for each source
    extension.
  example:
    config: |
      sources: [[/, file_system, src], [/, file_system, /mnt/pictures, '**/*.jpg']]

sources.ignore_paths:
  summary: |
    The path patterns that should be ignored. All paths that match at least one of the patterns
    are ignored.
  syntax: |
    `[PATTERN, ...]` where `PATTERN` is a valid path pattern
  example:
    config: |
      sources.ignore_paths: [**/*~, **/CVS/**]

tag.breadcrumb_trail.end_level:
  summary: |
    The level at which the breadcrumb trail ends. Have a look at the documentation for
    tag.breadcrumb_trail.start_level for more information on the useable level numbers.
  syntax: |
    `INTEGER` where `INTEGER` is an integer
  example:
    config: |
      tag.breadcrumb_trail.end_level: 2
    tag: |
      {breadcrumb_trail: {end_level: 2}}

tag.breadcrumb_trail.omit_dir_index:
  summary: |
    Specifies whether the last path component should be omitted if it is an index path.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.breadcrumb_trail.omit_dir_index: true
    tag: |
      {breadcrumb_trail: {omit_dir_index: true}}

tag.breadcrumb_trail.separator:
  summary: |
    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 like `<` need to be
    properly escaped)
  example:
    config: |
      tag.breadcrumb_trail.separator: '---'
    tag: |
      {breadcrumb_trail: {separator: ' --- '}}

tag.breadcrumb_trail.start_level:
  summary: |
    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 configuration
    option into account when specifying the level number.
  syntax: |
    `INTEGER` where `INTEGER` is an integer
  example:
    config: |
      tag.breadcrumb_trail.start_level: 2
    tag: |
      {breadcrumb_trail: {start_level: 2}}

tag.breadcrumb_trail.template:
  summary: |
    The template node used for rendering the tag. It has to contain the block
    'tag.breadcrumb_trail' because this block is used for rendering.
  syntax: |
    `PATH` where `PATH` is the (a)(l)cn of the template node
  example:
    config: |
      tag.breadcrumb_trail.template: /other.template
    tag: |
      {breadcrumb_trail: {template: /other.template}}

tag.coderay.bold_every:
  summary: |
    The interval at which the line numbers should appear bold.
  syntax: |
    `INTEGER` where `INTEGER` is an integer
  example:
    config: |
      tag.coderay.bold_every: 2
    tag: |
      {coderay:: {lang: ruby, bold_every: 2}}puts 5 + 5{coderay}

tag.coderay.css:
  summary: |
    Specifies how the highlighted code should be styled. If set to `style`, the CSS style
    attributes are set directly on the various HTML elements. If set to `class`, only classes are
    set on the HTML elements and the default external stylesheet is used - the content processor
    html_head is needed for this to work. If set to `other`, only classes are set like with the
    `class` value but no default external stylesheet is used.
  syntax: |
    `STYLE` where `STYLE` is either `style`, `css` or `other`
  example:
    config: |
      tag.coderay.css: style
    tag: |
      {coderay:: {lang: ruby, css: class}}puts 5 + 5{coderay}

tag.coderay.lang:
  summary: |
    The language used for highlighting.
  syntax: |
    `LANG` where `LANG` is one of the languages supported by coderay
  example:
    config: |
      tag.coderay.lang: ruby
    tag: |
      {coderay:: ruby}puts 5 + 5{coderay}

tag.coderay.line_number_start:
  summary: |
    The line number that should be used for the first line.
  syntax: |
    `INTEGER` where `INTEGER` is an integer
  example:
    config: |
      tag.coderay.line_number_start: 4
    tag: |
      {coderay:: {lang: ruby, line_number_start: 4}}puts 5 + 5{coderay}

tag.coderay.line_numbers:
  summary: |
    Specifies whether line numbers should be shown.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.coderay.line_numbers: false
    tag: |
      {coderay:: {lang: ruby, line_numbers: false}}puts 5 + 5{coderay}

tag.coderay.process_body:
  summary: |
    Specifies whether the body of the tag should be processed by the content processor tags first.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.coderay.process_body: false
    tag: |
      {coderay:: {lang: ruby, process_body: false}}puts 5 + 5{coderay}

tag.coderay.tab_width:
  summary: |
    The number of spaces that should be used to replace tabulator characters.
  syntax: |
    `INTEGER` where `INTEGER` is an integer
  example:
    config: |
      tag.coderay.tab_width: 4
    tag: |
      {coderay:: {lang: ruby, tab_width: 4}}puts 5 + 5{coderay}

tag.coderay.wrap:
  summary: |
    The HTML element the highlighted code should be wrapped in.
  syntax: |
    `WRAP` where `WRAP` is either `:div` or `:span`
  example:
    config: |
      tag.coderay.wrap: span
    tag: |
      {coderay:: {lang: ruby, wrap: span}}puts 5 + 5{coderay}

tag.date.format:
  summary: |
    The format that should be used for formatting the current date. The format string needs to be
    in a format supported by Ruby's Time#strftime method.
  syntax: |
    `FORMAT` where `FORMAT` is the date format string
  example:
    config: |
      tag.date.format: '%Y-%m-%d'
    tag: |
      {date: {format: '%Y-%m-%d'}}

tag.date.mi:
  summary: |
    The name of the meta information key (a date/time) which should be formatted.
  syntax: |
    `KEY` where `KEY` is the name of a meta information key
  example:
    tag: |
      {date: {mi: modified_at, format: '%Y-%m-%d'}}

tag.execute_command.command:
  summary: |
    The command that should be executed.
  syntax: |
    `COMMAND` where `COMMAND` is a string containing the command and its arguments
  example:
    tag: |
      {exeucte_cmd: echo hallo}

tag.execute_command.escape_html:
  summary: |
    Specifies whether special HTML characters in the output of the executed command should be
    escaped.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.execute_command.escape_html: false
    tag: |
      {execute_cmd: {command: 'echo hallo', escape_html: false}}

tag.execute_command.process_output:
  summary: |
    Specifies whether the output of the executed command should be further processed by the
    content processor tags.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.execute_command.process_output: false
    tag: |
      {execute_cmd: {command: 'echo hallo', process_output: false}}

tag.include_file.escape_html:
  summary: |
    Specifies whether special HTML characters in the content of the file should be escaped.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.include_file.escape_html: false
    tag: |
      {include_file: {filename: my_file.txt, escape_html: false}}

tag.include_file.filename:
  summary: |
    The name of the file that should be included. The filename needs to be relative to the website
    directory or an absolute path.
  syntax: |
    `FILENAME` where `FILENAME` is the name of a file
  example:
    tag: |
      {include_file: my_file.txt}

tag.include_file.process_output:
  summary: |
    Specifies whether the content of the file should be further processed by the content
    processor tags.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.include_file.process_output: false
    tag: |
      {include_file: {filename: my_file.txt, process_output: false}}

tag.langbar.mapping:
  summary: |
    A hash with a mapping from language codes to display strings. If there is no mapping for a
    language code, the language code itself is displayed.
  syntax: |
    `MAPPING` where `MAPPING` is a hash with the mappings
  example:
    config: |
      tag.langbar.mapping: {de: Deutsch, en: English}
    tag: |
      {menu: {mapping: {de: Deutsch, en: English}}}

tag.langbar.separator:
  summary: |
    The string that should be used as separator between the individual language parts.
  syntax: |
    `SEPARATOR` where `SEPARATOR` is a string (special HTML characters like `<` need to be
    properly escaped)
  example:
    config: |
      tag.langbar.separator: ' --- '
    tag: |
      {langbar: {separator: ' --- '}}

tag.langbar.show_own_lang:
  summary: |
    Specifies whether the link to the language of the current page should be displayed.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.langbar.show_own_lang: false
    tag: |
      {langbar: {show_own_lang: false}}

tag.langbar.show_single_lang:
  summary: |
    Specifies whether the langbar should be displayed even if there are no translations of the
    page (i.e. when there is only one page).
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.langbar.show_single_lang: false
    tag: |
      {langbar: {show_single_lang: false}}

tag.langbar.template:
  summary: |
    The template node used for rendering the tag. It has to contain the block
    'tag.langbar' because this block is used for rendering.
  syntax: |
    `PATH` where `PATH` is the (a)(l)cn of the template node
  example:
    config: |
      tag.langbar.template: /other.template
    tag: |
      {langbar: {template: /other.template}}

tag.link.attr:
  summary: |
    Additional HTML attributes that should be set on the generated link.
  syntax: |
    `{NAME: VALUE, ...}` where `NAME` is a valid HTML attribute name and `VALUE` its value
  example:
    config: |
      tag.link.attr: {title: DocuPage}
    tag: |
      {link: {path: docu.html, attr: {title: DocuPage}}}

tag.link.path:
  summary: |
    The (a)(l)cn or destination path to which a link should be created.
  syntax: |
    `PATH` where `PATH` is an (a)(l)cn or a destination path
  example:
    tag: |
      {link: docu.html}

tag.menu.css_class:
  summary: |
    The content of the class attribute of the top level list element.
  syntax: |
    `STRING` where `STRING` is a space-separated list of CSS class names
  example:
    tag: |
      {menu: {options: {in_menu: true}, css_class: sidebar menu}}

tag.menu.item_level_class:
  summary: |
    The CSS class that is used on list items to indicate the nesting level.
  syntax: |
    `STRING` where `STRING` is a CSS class name
  example:
    tag: |
      {menu: {options: {in_menu: true}, item_level_class: mlevel}}

tag.menu.item_submenu_class:
  summary: |
    The CSS class that is used on list items to indicate an item with a sub-menu.
  syntax: |
    `STRING` where `STRING` is a CSS class name
  example:
    tag: |
      {menu: {options: {in_menu: true}, item_submenu_class: submenu}}

tag.menu.item_submenu_inhierarchy_class:
  summary: |
    The CSS class that is used on list items to indicate an item that is in the hierarchy of the
    current page.
  syntax: |
    `STRING` where `STRING` is a CSS class name
  example:
    tag: |
      {menu: {options: {in_menu: true}, item_submenu_inhierarchy_class: submenu-hier}}

tag.menu.item_selected_class:
  summary: |
    The CSS class that is used on list items to indicate the current page.
  syntax: |
    `STRING` where `STRING` is a CSS class name
  example:
    tag: |
      {menu: {options: {in_menu: true}, item_selected_class: active}}

tag.menu.options:
  summary: |
    Node finder options that specify which nodes the menu should use.
  syntax: |
    `OPTIONS` where `OPTIONS` is a hash with node finder options
  example:
    tag: |
      {menu: {options: {in_menu: true, sort: sort_info, levels: [1,3]}}}

tag.menu.style:
  summary: |
    The menu rendering style that should be used. The value can either be 'nested' for a nested
    menu or 'flat' for a flat menu.

    For example, this would be a menu with style 'nested'

        ul           1
          li         2
            ul       3
              li     4
              li     5
          li         6

    and this with style 'flat'

        ul           1
          li         2
          li         6
        ul           3
          li         4
          li         5
  syntax: |
    `STYLE` where `STYLE` is either `nested` or `flat`
  example:
    config: |
      tag.menu.style: flat
    tag: |
      {menu: {options: {mi: {menu: true}}, style: nested}}

tag.menu.template:
  summary: |
    The template node used for rendering the tag. It has to contain the block
    'tag.menu' because this block is used for rendering.
  syntax: |
    `PATH` where `PATH` is the (a)(l)cn of the template node
  example:
    config: |
      tag.menu.template: /other.template
    tag: |
      {menu: {options: {mi: {menu: true}}, template: /other.template}}

tag.menu.tracking_style:
  summary: |
    Specifies which kind of information should be tracked by the 'nodes' item tracker
  syntax: |
    `STYLE` where `STYLE` is 'meta_info' (if only changed meta information should be tracked) or
    'content' (if the content should be tracked)
  example:
    tag: |
      {menu: {options: {in_menu: true, sort: sort_info}, tracking_style: content}}

tag.meta_info.escape_html:
  summary: |
    Specifies whether special HTML characters in the meta information value should be escaped.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.meta_info.escape_html: true
    tag: |
      {title: {escape_html: false}}
      {meta_info: {mi: title, escape_html: false}}

tag.meta_info.mi:
  summary: |
    The name of the meta information key the value of which should be output.
  syntax: |
    `KEY` where `KEY` is the name of a meta information key
  example:
    tag: |
      {title: }
      {meta_info: {mi: title}

tag.prefix:
  summary: |
    The prefix used for tag names to avoid name clashes when another content processor uses
    similar markup.
  syntax: |
    `PREFIX` where `PREFIX` is the prefix name
  example:
    config: |
      tag.prefix: webgen

tag.relocatable.ignore_unknown_fragment:
  summary: |
    Specifies whether an unknown, non-resolvable fragment part should be ignored.
  syntax: |
    `true` or `false`
  example:
    config: |
      tag.relocatable.ignore_unknown_fragment: true

tag.relocatable.path:
  summary: |
    The path that should be made relocatable.
  syntax: |
    `PATH` where `PATH` is an (a)(l)cn
  example:
    tag: |
      {relocatable: default.css}

tag.tikz.img_attr:
  summary: |
    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` its
    value.
  example:
    config: |
      tag.tikz.img_attr: {alt: Some TikZ picture}
    tag: |
      {tikz:: {path: tikz.png, img_attr: {alt: Some TikZ picture}}}
      \tikz \draw (0,0) -- (0,2) -- (2,2);
      {tikz}

tag.tikz.path:
  summary: |
    The source path that should be used for creating the TikZ image. The destination path is
    derived from this path the usual way. Don't use a path that does already exist!
  syntax: |
    `PATH` where `PATH` is a relative or absolute source path
  example:
    tag: |
      {tikz:: images/tikz.png}\tikz \draw (0,0) -- (0,2);{tikz}

website.cache:
  summary: |
    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's temporary 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`
  example:
    config: |
      website.cache: [file, my.cache]

website.dry_run:
  summary:
    Specifies whether anything should be written to the destination.
  syntax: |
    `true` or `false`.
  example:
    config: |
      website.dry_run: false

website.lang:
  summary: |
    The default language of the website. This language is assigned, for example, to page paths for
    which no language has explicitly been specified.
  syntax: |
    `LANGUAGE` where `LANGUAGE` is a ISO-639-1/2 two or three letter language code (e.g. 'de',
    'en', 'fr', ...)
  example:
    config: |
      website.lang: de

website.link_to_current_page:
  summary:
    Specifies whether generated links to the current page should be used. If `false`, then a
    `<span>` element is used instead of an `<a>` element.
  syntax: |
    `true` or `false`.
  example:
    config: |
      website.link_to_current_page: false

website.base_url:
  summary: |
    The base URL of the website. It is used to create absolute URLs when relative URLs won't
    work.
  syntax: |
    `URL` where `URL` is the base URL of the website
  example:
    config: |
      website.base_url: http://webgen.gettalong.org

website.tmpdir:
  summary: |
    The directory used for temporary files. It is taken relative to website directory and used for
    cache and temporary files created when webgen is run. Note that this directory *cannot* be
    shared between webgen websites!
  syntax: |
    `DIRECTORY` where `DIRECTORY` is a directory (relative to the website directory or absolute)
  example:
    config: |
      website.tmpdir: /tmp/webgen-tmp-dir