--- title: Configuration Option Reference in_menu: false --- <% def convert_proc(data, indent) res = if data.kind_of?(Array) data.inspect elsif data.kind_of?(String) (data.empty? ? '""' : data) elsif data.kind_of?(Hash) res = data.collect do |k,v| if v.kind_of?(Hash) k.to_s + ":\n" + convert_proc(v, 2) else k.to_s + ": " + convert_proc(v, 0) end end.join("\n") (res.empty? ? "{}" : res) elsif data.kind_of?(NilClass) "~" else data.inspect end res.split("\n").collect {|l| ' '*indent + l}.join("\n") end require 'tmpdir' ws = Webgen::Website.new(File.join(Dir.tmpdir, 'webgen' + Process.pid.to_s)) ws.init show_default = lambda do |option| "* Default value:\n\n#{convert_proc(ws.config[option], 10)}\n" end %> # Configuration Option Reference This reference describes all available configurations that can be set via the [configuration file]({relocatable: manual.html#website-configfile}) `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 <%= show_default['website.lang'] %> * 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` <%= show_default['website.link_to_current_page'] %> * 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` <%= show_default['website.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`. <%= show_default['common.sitemap.honor_in_menu'] %> * 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`. <%= show_default['common.sitemap.any_lang'] %> * 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. <%= show_default['common.sitemap.used_kinds'] %> * 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. <%= show_default['sources'] %> * 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]({relocatable: source/filesystem.html}) 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. <%= show_default['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. <%= show_default['output'] %> * 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`. <%= show_default['output.do_deletion'] %> * 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]({relocatable: manual.html#website-configfile}) 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. <%= show_default['sourcehandler.patterns'] %> * 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. <%= show_default['sourcehandler.invoke'] %> * 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`. <%= show_default['sourcehandler.casefold'] %> * 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`. <%= show_default['sourcehandler.use_hidden_files'] %> * 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. <%= show_default['sourcehandler.ignore'] %> * 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`. <%= show_default['sourcehandler.default_lang_in_output_path'] %> * 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. <%= show_default['sourcehandler.default_meta_info'] %> * 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. <%= show_default['sourcehandler.template.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`. <%= show_default['contentprocessor.map'] %> * 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`. <%= show_default['contentprocessor.erubis.use_pi'] %> * 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. <%= show_default['contentprocessor.erubis.options'] %> * Example for setting the option in the configuration file: contentprocessor.erubis.options: {:trim: true} * ### contentprocessor.kramdown.handle_links This configuration option can be used to specify whether all links generated via kramdown syntax should be automatically run through the [relocatable tag]({relocatable: tag/relocatable.html}). 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`. <%= show_default['contentprocessor.kramdown.handle_links'] %> * 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 <%= show_default['contentprocessor.kramdown.options'] %> * 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`. <%= show_default['contentprocessor.redcloth.hard_breaks'] %> * 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. <%= show_default['contentprocessor.tags.prefix'] %> * 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`. <%= show_default['contentprocessor.tags.map'] %> * 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`]({relocatable: contentprocessor/tidy.html}). * Syntax: `STRING` where `STRING` is the string holding the command line options. <%= show_default['contentprocessor.tidy.options'] %> * 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`]({relocatable: contentprocessor/xmllint.html}). * Syntax: `STRING` where `STRING` is the string holding the command line options. <%= show_default['contentprocessor.xmllint.options'] %> * 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) <%= show_default['tag.breadcrumbtrail.separator'] %> * 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`. <%= show_default['tag.breadcrumbtrail.omit_index_path'] %> * 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 <%= show_default['tag.breadcrumbtrail.start_level'] %> * 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 <%= show_default['tag.breadcrumbtrail.end_level'] %> * 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 <%= (require 'coderay'; CodeRay::Scanners.list.map {|n| '`' + n + '`'}.join(', ')) %>. <%= show_default['tag.coderay.lang'] %> * 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`. <%= show_default['tag.coderay.process_body'] %> * 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` <%= show_default['tag.coderay.wrap'] %> * 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`. <%= show_default['tag.coderay.line_numbers'] %> * 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. <%= show_default['tag.coderay.line_number_start'] %> * 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. <%= show_default['tag.coderay.bold_every'] %> * 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. <%= show_default['tag.coderay.tab_width'] %> * 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]({relocatable: contentprocessor/head.html}) 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`. <%= show_default['tag.coderay.css'] %> * 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](http://www.ruby-doc.org/core/classes/Time.html). * Syntax: `FORMAT` where `FORMAT` is a string. <%= show_default['tag.date.format'] %> * 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. <%= show_default['tag.executecommand.command'] %> * 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`. <%= show_default['tag.executecommand.process_output'] %> * 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`. <%= show_default['tag.executecommand.escape_html'] %> * 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 <%= show_default['tag.includefile.filename'] %> * 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`. <%= show_default['tag.includefile.process_output'] %> * 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`. <%= show_default['tag.includefile.escape_html'] %> * 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) <%= show_default['tag.langbar.separator'] %> * 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`. <%= show_default['tag.langbar.show_own_lang'] %> * 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`. <%= show_default['tag.langbar.show_single_lang'] %> * 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. <%= show_default['tag.langbar.lang_names'] %> * 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. <%= show_default['tag.link.path'] %> * 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. <%= show_default['tag.link.attr'] %> * 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`. <%= show_default['tag.metainfo.escape_html'] %> * 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` <%= show_default['tag.menu.used_nodes'] %> * 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. <%= show_default['tag.menu.start_level'] %> * 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. <%= show_default['tag.menu.min_levels'] %> * 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. <%= show_default['tag.menu.max_levels'] %> * 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`. <%= show_default['tag.menu.show_current_subtree_only'] %> * 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`. <%= show_default['tag.menu.nested'] %> * 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. <%= show_default['tag.relocatable.path'] %> * Example for setting the option directly in a tag: 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. <%= show_default['tag.tikz.path'] %> * 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. <%= show_default['tag.tikz.libraries'] %> * 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. <%= show_default['tag.tikz.opts'] %> * 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. <%= show_default['tag.tikz.resolution'] %> * 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`. <%= show_default['tag.tikz.transparent'] %> * 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. <%= show_default['tag.tikz.img_attr'] %> * 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} --- ## 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')