The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Markdown-Perl-1.06
River stage zero No dependents
2 ++
/ Markdown::Perl::Options

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.

Note also that only the modes are tested as coherent selves. Setting individual options on top of a given mode might result in inconsistent behavior.

OPTIONS

Options controlling which top-level blocks are used

parse_file_metadata (enum, default: yaml)

This option controls whether the parser accepts optional metadata at the beginning of the file. Currently, it does nothing with these metadata, even when they are accepted. In the future they might be used to build complete HTML file instead of just fragment.

The possible values are:

none

No file metadata is accepted, any structure in the document must be in Markdown.

yaml (default)

The parser accepts a YAML table as the very beginning of the document. This table must start with a line containing just --- and ends with another line containing --- or .... The content between these two markers must be valid a valid, non-empty YAML sequence and it cannot contain any empty line.

use_fenced_code_blocks (boolean, default: true)

This option 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, heading bar, paragraph baz

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, paragraph baz.

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, paragraph baz

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:

ignored

The info text is ignored.

language (default)

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.

render_naked_paragraphs (boolean, default: false)

When this is set to true, the <p> tag is always skipped around a paragraph. This is mostly meant to render short amount of text as pure Markdown inline content, without a surrounding block structure.

Options controlling which inline elements are used

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

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.

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)

This option provides a map from delimiter symbols to the matching HTML tags. This option should be passed as a comma-separated list of delimiter=tag_name values. For example, the original Markdown syntax map could be specified as *=em,**=strong,_=em,__=strong. The delimiters can only be made of a single unicode character or of twice the same unicode character. The values should be either HTML tag names (for example em, strong, etc.) or they can be arbitrary HTML class names, prefixed by a single dot (.). In the latter case the delimiters will be used to insert a <span> element, with the given class.

When using the programmatic interface, this map can be passed directly as a hash-reference, with the same content as described above.

inline_delimiters_max_run_length (map)

TODO: document

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.

two_spaces_hard_line_breaks (boolean, default: false)

Controls if a hard line break can be generated by ending a line with two spaces.

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.

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.

SEE ALSO

Markdown::Perl, pmarkdown