NAME
Configuration options for pmarkdown and Markdown::Perl
SYNOPSIS
This document describes the existing configuration options for the Markdown::Perl library and the pmarkdown program. Please refer to their documentation to know how to set and use these options.
MODES
In addition to setting individual options, you can set bundle of options together using modes. See the "MODES" in pmarkdown documentation for a list of available modes. And see the documentation for Markdown::Perl or pmarkdown to learn how to set a mode.
Note that all options are applied on top of the selected mode. Even if the options are passed before the mode, the mode will not override the options.
OPTIONS
Options controlling which top-level blocks are used
use_fenced_code_blocks (boolean, default: true)
This options controls whether fenced code blocks are recognised in the document structure.
use_table_blocks (boolean, default: true)
This options controls whether table blocks can be used.
use_setext_headings (boolean, default: false)
This options controls whether table blocks can be used.
Options controlling the parsing of top-level blocks
fenced_code_blocks_must_be_closed (boolean, default: true)
By default, a fenced code block with no closing fence will run until the end of the document. With this setting, the opening fence will be treated as normal text, rather than the start of a code block, if there is no matching closing fence.
multi_lines_setext_headings (enum, default: multi_line)
The default behavior of setext headings in the CommonMark spec is that they can have multiple lines of text preceding them (forming the heading itself).
This option allows to change this behavior. And is illustrated with this example of Markdown:
Foo
bar
---
baz
The possible values are:
- single_line
-
Only the last line of text is kept as part of the heading. The preceding lines are a paragraph of themselves. The result on the example would be: paragraph
Foo
, headingbar
, paragraphbaz
- break
-
If the heading underline can be interpreted as a thematic break, then it is interpreted as such (normally the heading interpretation takes precedence). The result on the example would be: paragraph
Foo bar
, thematic break, paragraphbaz
.If the heading underline cannot be interpreted as a thematic break, then the heading will use the default multi_line behavior.
- multi_line (default)
-
This is the default CommonMark behavior where all the preceding lines are part of the heading. The result on the example would be: heading
Foo bar
, paragraphbaz
- ignore
-
The heading is ignored, and form just one large paragraph. The result on the example would be: paragraph
Foo bar --- baz
.Note that this actually has an impact on the interpretation of the thematic breaks too.
lists_can_interrupt_paragraph (enum, default: strict)
Specify whether and how a list can interrupt a paragraph.
- never
-
A list can never interrupt a paragraph.
- within_list
-
A list can interrupt a paragraph only when we are already inside another list.
- strict (default)
-
A list can interrupt a paragraph but only with some non ambiguous list markers.
- always
-
A list can always interrupt a paragraph.
allow_task_list_markers (enum, default: list)
Specify whether task list markers (rendered as check boxes) are recognised in the input. The possible values are as follow:
- never
-
Task list marker are never recognised
- list (default)
-
Task list markers are recognised only as the first element at the beginning of a list item.
- always
-
Task list markers are recognised at the beginning of any paragraphs, inside any type of block.
table_blocks_can_interrupt_paragraph (boolean, default: false)
Allow a table top level block to interrupt a paragraph.
table_blocks_pipes_requirements (enum, default: strict)
Defines how strict is the parsing of table top level blocks when the leading or trailing pipes of a given line are missing.
- strict (default)
-
Leading and trailing pipes are always required for all the lines of the table.
- loose
-
Leading and trailing pipes can be omitted when the table is not interrupting a paragraph, if it has at least two columns, and if the delimiter row uses delimiters with more than one character.
- lenient
-
Leading and trailing pipes can be omitted when the table has at least two columns, and if the delimiter row uses delimiters with more than one character.
- lax
-
Leading and trailing pipes can always be omitted, except on the header line of a table, if it has a single column.
Options controlling the rendering of top-level blocks
code_blocks_info (enum, default: language)
Fenced code blocks can have info strings on their opening lines (any text after the ```
or ~~~
fence). This option controls what is done with that text.
The possible values are:
code_blocks_convert_tabs_to_spaces (boolean, default: false)
By default, tabs are preserved inside code blocks. With this option, all tabs (at the beginning of the lines or inside) are turned into spaces, aligned with the tab stops (currently always a multiple of 4).
table_blocks_have_cells_for_missing_data (boolean, default: false)
Whether a table will have a cell in HTML for a missing cell in the markdown input.
Options controlling which inline elements are used
use_extended_autolinks (boolean, default: true)
Allow some links to be recognised when they appear in plain text. These links must start by http://
, https://
, or www.
.
Options controlling the parsing of inline elements
autolinks_regex (regex string)
The regex that an autolink must match. This is for CommonMark autolinks, that are recognized only if they appear between brackets \<link\
>.
The default value is meant to match the spec. Basically it requires a scheme (e.g. https:
) followed by mostly anything else except that spaces and the bracket symbols (\<
and \
>) must be escaped.
autolinks_email_regex (regex string)
The regex that an autolink must match to be recognised as an email address. This allows to omit the mailto:
scheme that would be needed to be recognised as an autolink otherwise.
The default value is exactly the regex specified by the spec.
inline_delimiters (map)
TODO: document TODO: provide a way to add entries to this option without redefining it entirely (when used on the command line).
inline_delimiters_max_run_length (map)
TODO: document
allow_spaces_in_links (enum, default: none)
This option controls whether spaces are allowed between the link text and the link destination (between the closing bracket of the text and the opening parenthesis or bracket of the destination).
- none (default)
-
No space is allowed between the link text and the link target.
- reference
-
This allows at most one space between the two sets of brackets in a reference link.
Options controlling the rendering of inline elements
html_escaped_characters (character_class)
This option specifies the list of characters that will be escaped in the HTML output. This should be a string containing the characters to escapes. Only the following characters are supported and can be passed in the string: "
, '
, &
, <
, and >
.
html_escaped_code_characters (character_class)
This option is similar to the html_escaped_characters
but is used in the context of <code>
blocks.
force_final_new_line (boolean, default: false)
This option forces the processing of the input markdown to behave as if a final new line was always present. Note that, even without this option, a final new line will almost always be present in the output (and will always be present with it).
preserve_white_lines (boolean, default: true)
By default, pmarkdown will try to preserve lines that contains only whitespace when possible. If this option is set to false, such lines are treated as if they contained just the new line character.
disallowed_html_tags (world list)
This option specifies a comma separated list (or, in Perl, an array reference) of name of HTML tags that will be disallowed in the output. If these tags appear they will be deactivated in the output.
default_extended_autolinks_scheme (enum, default: https)
Specify which scheme is added to the beginning of extended autolinks when none was present initially.
Other options
warn_for_unused_input (boolean, default: true)
In general, all user input is present in the output (possibly as uninterpreted text if it was not understood). But some valid Markdown construct results in parts of the input being ignored. By default pmarkdown
will emit a warning when such a construct is found. This option can disable these warnings.