Configuration Option Reference

This reference describes all available configurations that can be set via the configuration file config.yaml (or, if you want to have more control, via an extension file).

The reference is splitted into sections to provide better navigation. A sub header under a category always specifies the name of a configuration option and after that comes a description and example code. The example code either shows how to set this option in the configuration file (for most configuration options) and/or how to use it in a webgen tag (for tag configuration options).

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

    • Default value:

      en

    • Example for setting the option in the configuration file:

      website.lang: de

  • 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

    • Default value:

      false

    • Example for setting the option in the configuration file:

      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

    • Default value:

      [:file, "webgen.cache"]

    • Example for setting the option in the configuration file:

      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.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      common.sitemap.honor_in_menu: true

      Example for setting the option directly in a tag:

      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.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      common.sitemap.any_lang: true

      Example for setting the option directly in a tag:

      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.

    • Default value:

      ["page"]

    • Example for setting the option in the configuration file:

      common.sitemap.used_kinds: [asset]

      Example for setting the option directly in a tag:

      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.

    • Default value:

      [["/", "Webgen::Source::FileSystem", "src"]]

    • Example for setting the option in the configuration file:

      sources: [[/, Webgen::Source::FileSystem, src], [/, Webgen::Source::FileSystem, /mnt/pictures, **/*.jpg]]

      Also have a look at the file system source documentation for more examples!

  • passive_sources

    Specifies one or more sources which are not actively used during the node creation time, ie. no nodes are created from these sources by default. Instead, they lie dormant until later and are only used if resolving a path fails. Then it is checked if a passive source for the requested path exists and if so, a node is created from it. If a node created from a passive source is not used anymore, it is automatically deleted.

    • 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.

    • Default value:

      [["/", "Webgen::Source::Resource", "webgen-passive-sources"]]

    • Example for setting the option in the configuration file:

      passive_sources:
  [[/, Webgen::Source::Resource, webgen-passive-sources], [/, 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.

    • Default value:

      ["Webgen::Output::FileSystem", "out"]

    • Example for setting the option in the configuration file:

      output: [Webgen::Output::FileSystem, custom_out]

  • output.do_deletion

    Specifies whether the output class should delete generated paths once the source paths are not available anymore.

    • Syntax: BOOLEAN where BOOLEAN is either true or false.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      output.do_deletion: true

  • sourcehandler.patterns

    Specifies the path patterns that are used by the individual source handlers. This configuration option is not normally set directly in the configuration file but either in an extension file (e.g. ext/init.rb) or using a configuration file helper 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.

    • Default value:

      Webgen::SourceHandler::Copy: ["**/*.css", "**/*.js", "**/*.html", "**/*.gif", "**/*.jpg", "**/*.png", "**/*.ico"]
Webgen::SourceHandler::Directory: ["**/"]
Webgen::SourceHandler::Metainfo: ["**/metainfo", "**/*.metainfo"]
Webgen::SourceHandler::Template: ["**/*.template"]
Webgen::SourceHandler::Page: ["**/*.page"]
Webgen::SourceHandler::Virtual: ["**/virtual", "**/*.virtual"]
Webgen::SourceHandler::Feed: ["**/*.feed"]
Webgen::SourceHandler::Sitemap: ["**/*.sitemap"]

    • Example for setting the option in ext/init.rb:

      config = Webgen::WebsiteAccess.website.config
config['sourcehandler.patterns']['Webgen::SourceHandler::Copy'] << '**/*.swf'

      Example for setting the option via the configuration file helper in the configuration file:

      patterns:
  Copy:
    add: [**/*.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.

    • Default value:

      1: ["Webgen::SourceHandler::Directory", "Webgen::SourceHandler::Metainfo"]
5: ["Webgen::SourceHandler::Copy", "Webgen::SourceHandler::Template", "Webgen::SourceHandler::Page", "Webgen::SourceHandler::Feed", "Webgen::SourceHandler::Sitemap"]
9: ["Webgen::SourceHandler::Virtual"]

    • Example for setting the option in ext/init.rb:

      config = Webgen::WebsiteAccess.website.config
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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      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.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      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.

    • Default value:

      ["**/*~", "**/.svn/**"]

    • Example for setting the option in the configuration file:

      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.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      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.

    • Default value:

      all:
  output_path: standard
  output_path_style: [:parent, :basename, [".", :lang], :ext]
Webgen::SourceHandler::Copy:
  kind: asset
Webgen::SourceHandler::Directory:
  index_path: index.html
  kind: directory
Webgen::SourceHandler::Page:
  kind: page
  fragments_in_menu: true
  blocks:
    default:
      pipeline: erb,tags,markdown,blocks,fragments
Webgen::SourceHandler::Fragment:
  kind: fragment
Webgen::SourceHandler::Template:
  blocks:
    default:
      pipeline: erb,tags,blocks,head
Webgen::SourceHandler::Metainfo:
  blocks:
    1:
      name: paths
    2:
      name: alcn
Webgen::SourceHandler::Feed:
  rss: true
  atom: true
  blocks:
    default:
      pipeline: erb
Webgen::SourceHandler::Sitemap:
  default_priority: 0.5
  default_change_freq: weekly
  common.sitemap.any_lang: true
  blocks:
    default:
      pipeline: erb

    • Example for setting the option in the configuration file:

      default_meta_info:
  :all:
    output_path_style: [:parent, :basename, :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.

    • Default value:

      default.template

    • Example for setting the option in the configuration file:

      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 processing 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, SHORT: [NAME, TYPE], ...} where SHORT is the short name of the content processor class NAME. The second form allows one to additionally specify the type TYPE of the content processor which has to be :binary or :text. If the first form is used, then the type defaults to :text.

    • Default value:

      markdown: Webgen::ContentProcessor::Kramdown
maruku: Webgen::ContentProcessor::Maruku
textile: Webgen::ContentProcessor::RedCloth
redcloth: Webgen::ContentProcessor::RedCloth
tags: Webgen::ContentProcessor::Tags
blocks: Webgen::ContentProcessor::Blocks
erb: Webgen::ContentProcessor::Erb
haml: Webgen::ContentProcessor::Haml
sass: Webgen::ContentProcessor::Sass
scss: Webgen::ContentProcessor::Scss
rdoc: Webgen::ContentProcessor::RDoc
builder: Webgen::ContentProcessor::Builder
erubis: Webgen::ContentProcessor::Erubis
rdiscount: Webgen::ContentProcessor::RDiscount
fragments: Webgen::ContentProcessor::Fragments
head: Webgen::ContentProcessor::Head
tidy: Webgen::ContentProcessor::Tidy
xmllint: Webgen::ContentProcessor::Xmllint
kramdown: Webgen::ContentProcessor::Kramdown
less: Webgen::ContentProcessor::Less

    • Examples for setting the option in ext/init.rb:

      config = Webgen::WebsiteAccess.website.config
config['contentprocessor.map']['newcp'] = 'Extension::MyNewContentProcessor'
config['contentprocessor.map']['newcp'] = ['Extension::MyNewContentProcessor', :binary]

  • 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.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      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.

    • Default value:

      {}

    • Example for setting the option in the configuration file:

      contentprocessor.erubis.options: {:trim: true}

  • This configuration option can be used to specify whether all links generated via kramdown syntax should be automatically run through the relocatable tag. 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: BOOLEAN where BOOLEAN is either true or false.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      contentprocessor.kramdown.handle_links: false

  • contentprocessor.kramdown.options

    This configuration option can be used to specify processing and converting options for kramdown.

    • Syntax: {KEY: VALUE, ...} where KEY and VALUE are key-value pairs of kramdown options

    • Default value:

      auto_ids: true

    • Example for setting the option in the configuration file:

      contentprocessor.kramdown.options: {:auto_ids: false}

  • contentprocessor.redcloth.hard_breaks

    Specifies whether hard breaks (i.e. single newlines) in paragraphs are converted to HTML break tags.

    • Syntax: BOOLEAN where BOOLEAN is either true or false.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      contentprocessor.redcloth.hard_breaks: 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.

    • Default value:

      ""

    • Example for setting the option in the configuration file:

      contentprocessor.tags.prefix: webgen

  • 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.

    • Default value:

      relocatable: Webgen::Tag::Relocatable
menu: Webgen::Tag::Menu
breadcrumb_trail: Webgen::Tag::BreadcrumbTrail
langbar: Webgen::Tag::Langbar
include_file: Webgen::Tag::IncludeFile
execute_cmd: Webgen::Tag::ExecuteCommand
coderay: Webgen::Tag::Coderay
date: Webgen::Tag::Date
sitemap: Webgen::Tag::Sitemap
tikz: Webgen::Tag::TikZ
link: Webgen::Tag::Link
default: Webgen::Tag::Metainfo

    • Example for setting the option in ext/init.rb:

      config = Webgen::WebsiteAccess.website.config
config['contentprocessor.tags.map']['highlight'] = 'Extension::MyHighlightingTag'

  • contentprocessor.tidy.options

    This configuration option can be used to set the command line options for the tidy program which is used by the content processor tidy.

    • Syntax: STRING where STRING is the string holding the command line options.

    • Default value:

      -raw

    • Example for setting the option in the configuration file:

      contentprocessor.tidy.options: "-utf8"

  • contentprocessor.xmllint.options

    This configuration option can be used to set the command line options for the xmllint program which is used by the content processor xmllint.

    • Syntax: STRING where STRING is the string holding the command line options.

    • Default value:

      --catalogs --noout --valid

    • Example for setting the option in the configuration file:

      contentprocessor.xmllint.options: "--catalogs --noout"

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 options described in this section have an example which shows how to use the option in files in Webgen Page Format and most options also have an example which shows how to set the option in the configuration file.

  • 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)

    • Default value:

       /

    • Example for setting the option in the configuration file:

      tag.breadcrumbtrail.separator: '---'

      Example for setting the option directly in a tag:

      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.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      tag.breadcrumbtrail.omit_index_path: true

      Example for setting the option directly in a tag:

      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

    • Default value:

      0

    • Example for setting the option in the configuration file:

      tag.breadcrumbtrail.start_level: 2

      Example for setting the option directly in a tag:

      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

    • Default value:

      -1

    • Example for setting the option in the configuration file:

      tag.breadcrumbtrail.end_level: 2

      Example for setting the option directly in a tag:

      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 debug, plaintext, yaml, ruby, xml, sql, rhtml, groovy, cpp, html, nitro_xhtml, diff, c, json, python, java, java_script, php, scheme, delphi, css.

    • Default value:

      ruby

    • Example for setting the option in the configuration file:

      tag.coderay.lang: ruby

      Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.coderay.process_body: false

      Example for setting the option directly in a tag:

      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

    • Default value:

      :div

    • Example for setting the option in the configuration file:

      tag.coderay.wrap: span

      Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.coderay.line_numbers: false

      Example for setting the option directly in a tag:

      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.

    • Default value:

      1

    • Example for setting the option in the configuration file:

      tag.coderay.line_number_start: 4

      Example for setting the option directly in a tag:

      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.

    • Default value:

      10

    • Example for setting the option in the configuration file:

      tag.coderay.bold_every: 2

      Example for setting the option directly in a tag:

      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.

    • Default value:

      8

    • Example for setting the option in the configuration file:

      tag.coderay.tab_width: 4

      Example for setting the option directly in a tag:

      tabulator == 4 spaces: {coderay:: {lang: ruby, tab_width: 4}}puts 5 + 5{coderay}

  • tag.coderay.css

    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 a default external stylesheet is used - the content processor 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. You have to provide the styles yourself.

    • Syntax: STYLE where STYLE is either style, css or other.

    • Default value:

      :style

    • Example for setting the option in the configuration file:

      tag.coderay.css: style

      Example for setting the option directly in a tag:

      with external stylesheet: {coderay:: {lang: ruby, css: class}}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.

    • Syntax: FORMAT where FORMAT is a string.

    • Default value:

      %Y-%m-%d %H:%M:%S

    • Example for setting the option in the configuration file:

      tag.date.format: '%Y-%m-%d'

      Example for setting the option directly in a tag:

      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.

    • Default value:

      ~

    • Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.executecommand.process_output: false

      Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.executecommand.escape_html: false

      Example for setting the option directly in a tag:

      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

    • Default value:

      ~

    • Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.includefile.process_output: false

      Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.includefile.escape_html: false

      Example for setting the option directly in a tag:

      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)

    • Default value:

       |

    • Example for setting the option in the configuration file:

      tag.langbar.separator: ' --- '

      Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.langbar.show_own_lang: false

      Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.langbar.show_single_lang: false

      Example for setting the option directly in a tag:

      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.

    • Default value:

      {}

    • Example for setting the option in the configuration file:

      tag.langbar.lang_names: {de: Deutsch, en: English}

      Example for setting the option directly in a tag:

      Langbar with custom language names: {langbar: {lang_names: {de: Deutsch, en: English}}}

  • tag.link.path

    The default mandatory configuration option for Tag::Link that specifies the (AL)CN path to which should be linked.

    • Syntax: PATH where PATH is an (absolute) (localized) canonical name.

    • Default value:

      ~

    • Example for setting the option directly in a tag:

      You will find more information on the {link: docu.html} page!

  • tag.link.attr

    Specifies additional HTML attributes that should be set on the link generated by Tag::Link.

    • Syntax: {NAME: VALUE, ...} where NAME is a valid HTML attribute name and VALUE its value.

    • Default value:

      {}

    • Example for setting the option in the configuration file:

      tag.link.attr: {title: DocuPage}

      Example for setting the option directly in a tag:

      You will find more info on the {link: {path: docu.html, attr: {title: DocuPage}}} page!

  • tag.metainfo.escape_html

    Specifies whether special HTML characters in the meta information value should be escaped.

    • Syntax: BOOLEAN where BOOLEAN is either true or false.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.metainfo.escape_html: false

      Example for setting the option directly in a tag:

      value of meta info `title` is not escaped {title: {escape_html: false}}

  • 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

    • Default value:

      all

    • Example for setting the option in the configuration file:

      tag.menu.used_nodes: fragments

      Example for setting the option directly in a tag:

      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.

    • Default value:

      1

    • Example for setting the option in the configuration file:

      tag.menu.start_level: 2

      Example for setting the option directly in a tag:

      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.

    • Default value:

      1

    • Example for setting the option in the configuration file:

      tag.menu.min_levels: 2

      Example for setting the option directly in a tag:

      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.

    • Default value:

      3

    • Example for setting the option in the configuration file:

      tag.menu.max_levels: 2

      Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.menu.show_current_subtree_only: false

      Example for setting the option directly in a tag:

      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.

    • Default value:

      true

    • Example for setting the option in the configuration file:

      tag.menu.nested: false

      Example for setting the option directly in a tag:

      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.

    • Syntax: PATH where PATH is a (localized) canonical name.

    • Default value:

      ~

    • Example for setting the option directly in a tag:

      <a href="{relocatable: ../features.html}">Some Path</a>

  • 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.

    • Default value:

      ~

    • Example for setting the option directly in a tag:

      {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.

    • Default value:

      ~

    • Example for setting the option in the configuration file:

      tag.tikz.libraries: [mindmap, arrows]

      Example for setting the option directly in a tag:

      {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.

    • Default value:

      ~

    • Example for setting the option in the configuration file:

      tag.tikz.opts: 'scale=3, line cap=round'

      Example for setting the option directly in a tag:

      {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 be 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.

    • Default value:

      72 72

    • Example for setting the option in the configuration file:

      tag.tikz.resolution: 300 72

      Example for setting the option directly in a tag:

      {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.

    • Default value:

      false

    • Example for setting the option in the configuration file:

      tag.tikz.transparent: true

      Example for setting the option directly in a tag:

      {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.

    • Default value:

      {}

    • Example for setting the option in the configuration file:

      tag.tikz.img_attr: {alt: Some TikZ picture}

      Example for setting the option directly in a tag:

      {tikz:: {path: images/tikz.png, img_attr: {alt: Some TikZ picture}}}
\tikz \draw (0,0) -- (0,2) -- (2,2);
{tikz}