Ubuntu Manpage: kramdown - a fast, pure-Ruby Markdown-superset converter

Provided by: kramdown_1.17.0-4ubuntu0.2_all

NAME

       kramdown - a fast, pure-Ruby Markdown-superset converter

SYNOPSIS

       kramdown [options] [FILE...]

DESCRIPTION

       kramdown  is  primarily  used  for  parsing  a  superset  of Markdown and converting it to
       different output formats. It supports standard Markdown (with  some  minor  modifications)
       and  various  extensions like tables and definition lists. Due to its modular architecture
       it also allows other input formats than Markdown, for example,  HTML  or  Github  Flavored
       Markdown.

       If FILE is not specified, kramdown reads from the standard input. The result is written to
       the standard output.

       There are two sets of options that kramdown accepts: The first one  includes  the  options
       that  are  used  directly  by  the kramdown binary. The second set of options controls how
       kramdown parses and converts its input.

       Default values for this second set can be  set  using  YAML  via  the  configuration  file
       kramdownrc.  Note  that configuration option names use underscores, not dashes (dashes are
       just used in the CLI options names), and boolean options do not have a no  variant  but  a
       value  of  true  or  false.  This  file  has  to  be  in  XDG_CONFIG_HOME  on  Linux/Unix,
       ~/Library/Preferences on macOS and ~/AppData/Local on Windows.

CLI-ONLY OPTIONS

       -i FORMAT, --input FORMAT
              Specify the input format. Available input formats: kramdown (this is the  default),
              markdown, GFM or html.

       -o FORMAT, --output FORMAT
              Specify  one  or more output formats separated by commas: html (default), kramdown,
              latex, pdf, man or remove_html_tags.

       --no-config-file
              Do  not  read  any  configuration  file.  Default  behavior  is  to  check  for   a
              configuration file and read it if it exists.

       --config-file FILE
              Override the default path and name of the configuration file.

       -v, --version
              Show the version of kramdown.

       -h, --help
              Show the help.

KRAMDOWN OPTIONS

--auto-id-prefix ARG
Prefix used for automatically generated header IDs

This option can be used to set a prefix for the automatically generated header IDs
so that there is no conflict when rendering multiple kramdown documents into one
output file separately. The prefix should only contain characters that are valid in
an ID!

Default: ‘’ Used by: HTML/Latex converter

--[no-]auto-id-stripping
Strip all formatting from header text for automatic ID generation

If this option is true, only the text elements of a header are used for generating
the ID later (in contrast to just using the raw header text line).

This option will be removed in version 2.0 because this will be the default then.

Default: false Used by: kramdown parser

--[no-]auto-ids
Use automatic header ID generation

If this option is true, ID values for all headers are automatically generated if no
ID is explicitly specified.

Default: true Used by: HTML/Latex converter

--coderay-bold-every ARG
Defines how often a line number should be made bold

Can either be an integer or false (to turn off bold line numbers completely).

Default: 10 Used by: HTML converter

--coderay-css ARG
Defines how the highlighted code gets styled

Possible values are :class (CSS classes are applied to the code elements, one must
supply the needed CSS file) or :style (default CSS styles are directly applied to
the code elements).

Default: style Used by: HTML converter

--coderay-default-lang ARG
Sets the default language for highlighting code blocks

If no language is set for a code block, the default language is used instead. The
value has to be one of the languages supported by coderay or nil if no default
language should be used.

Default: nil Used by: HTML converter

--coderay-line-number-start ARG
The start value for the line numbers

Default: 1 Used by: HTML converter

--coderay-line-numbers ARG
Defines how and if line numbers should be shown

The possible values are :table, :inline or nil. If this option is nil, no line
numbers are shown.

Default: :inline Used by: HTML converter

--coderay-tab-width ARG
The tab width used in highlighted code

Used by: HTML converter

--coderay-wrap ARG
Defines how the highlighted code should be wrapped

The possible values are :span, :div or nil.

Default: :div Used by: HTML converter

--[no-]enable-coderay
Use coderay for syntax highlighting

If this option is true, coderay is used by the HTML converter for syntax
highlighting the content of code spans and code blocks.

Default: true Used by: HTML converter

--entity-output ARG
Defines how entities are output

The possible values are :as_input (entities are output in the same form as found in
the input), :numeric (entities are output in numeric form), :symbolic (entities are
output in symbolic form if possible) or :as_char (entities are output as characters
if possible, only available on Ruby 1.9).

Default: :as_char Used by: HTML converter, kramdown converter

--footnote-backlink ARG
Defines the text that should be used for the footnote backlinks

The footnote backlink is just text, so any special HTML characters will be escaped.

If the footnote backlint text is an empty string, no footnote backlinks will be
generated.

Default: '&8617;' Used by: HTML converter

--[no-]footnote-backlink-inline
Specifies whether the footnote backlink should always be inline

With the default of false the footnote backlink is placed at the end of the last
paragraph if there is one, or an extra paragraph with only the footnote backlink is
created.

Setting this option to true tries to place the footnote backlink in the last,
possibly nested paragraph or header. If this fails (e.g. in the case of a table),
an extra paragraph with only the footnote backlink is created.

Default: false Used by: HTML converter

--footnote-nr ARG
The number of the first footnote

This option can be used to specify the number that is used for the first footnote.

Default: 1 Used by: HTML converter

--gfm-quirks ARG
Enables a set of GFM specific quirks

The way how GFM is transformed on Github often differs from the way kramdown does
things. Many of these differences are negligible but others are not.

This option allows one to enable/disable certain GFM quirks, i.e. ways in which GFM
parsing differs from kramdown parsing.

The value has to be a list of quirk names that should be enabled, separated by
commas. Possible names are:

• paragraph_end

Disables the kramdown restriction that at least one blank line has to be used
after a paragraph before a new block element can be started.

Note that if this quirk is used, lazy line wrapping does not fully work
anymore!

• no_auto_typographic

Disables automatic conversion of some characters into their corresponding
typographic symbols (like -- to em-dash etc). This helps to achieve results
closer to what GitHub Flavored Markdown produces.

Default: paragraph_end Used by: GFM parser

--[no-]hard-wrap
Interprets line breaks literally

Insert HTML <br /> tags inside paragraphs where the original Markdown document had
newlines (by default, Markdown ignores these newlines).

Default: true Used by: GFM parser

--header-offset ARG
Sets the output offset for headers

If this option is c (may also be negative) then a header with level n will be
output as a header with level c+n. If c+n is lower than 1, level 1 will be used. If
c+n is greater than 6, level 6 will be used.

Default: 0 Used by: HTML converter, Kramdown converter, Latex converter

--[no-]html-to-native
Convert HTML elements to native elements

If this option is true, the parser converts HTML elements to native elements. For
example, when parsing <em>hallo</em> the emphasis tag would normally be converted
to an :html element with tag type :em. If html_to_native is true, then the emphasis
would be converted to a native :em element.

This is useful for converters that cannot deal with HTML elements.

Default: false Used by: kramdown parser

--latex-headers ARG
Defines the LaTeX commands for different header levels

The commands for the header levels one to six can be specified by separating them
with commas.

Default: section,subsection,subsubsection,paragraph,subparagraph,subparagraph Used
by: Latex converter

--line-width ARG
Defines the line width to be used when outputting a document

Default: 72 Used by: kramdown converter

--link-defs ARG
Pre-defines link definitions

This option can be used to pre-define link definitions. The value needs to be a
Hash where the keys are the link identifiers and the values are two element Arrays
with the link URL and the link title.

If the value is a String, it has to contain a valid YAML hash and the hash has to
follow the above guidelines.

Default: {} Used by: kramdown parser

--math-engine ARG
Set the math engine

Specifies the math engine that should be used for converting math blocks/spans. If
this option is set to +nil+, no math engine is used and the math blocks/spans are
output as is.

Options for the selected math engine can be set with the math_engine_opts
configuration option.

Default: mathjax Used by: HTML converter

--math-engine-opts ARG
Set the math engine options

Specifies options for the math engine set via the math_engine configuration option.

The value needs to be a hash with key-value pairs that are understood by the used
math engine.

Default: {} Used by: HTML converter

--[no-]parse-block-html
Process kramdown syntax in block HTML tags

If this option is true, the kramdown parser processes the content of block HTML
tags as text containing block-level elements. Since this is not wanted normally,
the default is false. It is normally better to selectively enable kramdown
processing via the markdown attribute.

Default: false Used by: kramdown parser

--[no-]parse-span-html
Process kramdown syntax in span HTML tags

If this option is true, the kramdown parser processes the content of span HTML tags
as text containing span-level elements.

Default: true Used by: kramdown parser

--[no-]remove-block-html-tags
Remove block HTML tags

If this option is true, the RemoveHtmlTags converter removes block HTML tags.

Default: true Used by: RemoveHtmlTags converter

--[no-]remove-span-html-tags
Remove span HTML tags

If this option is true, the RemoveHtmlTags converter removes span HTML tags.

Default: false Used by: RemoveHtmlTags converter

--smart-quotes ARG
Defines the HTML entity names or code points for smart quote output

The entities identified by entity name or code point that should be used for, in
order, a left single quote, a right single quote, a left double and a right double
quote are specified by separating them with commas.

Default: lsquo,rsquo,ldquo,rdquo Used by: HTML/Latex converter

--syntax-highlighter ARG
Set the syntax highlighter

Specifies the syntax highlighter that should be used for highlighting code blocks
and spans. If this option is set to +nil+, no syntax highlighting is done.

Options for the syntax highlighter can be set with the syntax_highlighter_opts
configuration option.

Default: coderay Used by: HTML/Latex converter

--syntax-highlighter-opts ARG
Set the syntax highlighter options

Specifies options for the syntax highlighter set via the syntax_highlighter
configuration option.

The value needs to be a hash with key-value pairs that are understood by the used
syntax highlighter.

Default: {} Used by: HTML/Latex converter

--template ARG
The name of an ERB template file that should be used to wrap the output or the ERB
template itself.

This is used to wrap the output in an environment so that the output can be used as
a stand-alone document. For example, an HTML template would provide the needed
header and body tags so that the whole output is a valid HTML file. If no template
is specified, the output will be just the converted text.

When resolving the template file, the given template name is used first. If such a
file is not found, the converter extension (the same as the converter name) is
appended. If the file still cannot be found, the templates name is interpreted as a
template name that is provided by kramdown (without the converter extension). If
the file is still not found, the template name is checked if it starts with
‘string://’ and if it does, this prefix is removed and the rest is used as template
content.

kramdown provides a default template named ‘document’ for each converter.

Default: ‘’ Used by: all converters

--toc-levels ARG
Defines the levels that are used for the table of contents

The individual levels can be specified by separating them with commas (e.g. 1,2,3)
or by using the range syntax (e.g. 1..3). Only the specified levels are used for
the table of contents.

Default: 1..6 Used by: HTML/Latex converter

--[no-]transliterated-header-ids
Transliterate the header text before generating the ID

Only ASCII characters are used in headers IDs. This is not good for languages with
many non-ASCII characters. By enabling this option the header text is
transliterated to ASCII as good as possible so that the resulting header ID is more
useful.

The stringex library needs to be installed for this feature to work!

Default: false Used by: HTML/Latex converter

--typographic-symbols ARG
Defines a mapping from typographical symbol to output characters

Typographical symbols are normally output using their equivalent Unicode codepoint.
However, sometimes one wants to change the output, mostly to fallback to a sequence
of ASCII characters.

This option allows this by specifying a mapping from typographical symbol to its
output string. For example, the mapping {hellip: ...} would output the standard
ASCII representation of an ellipsis.

The available typographical symbol names are:

• hellip: ellipsis

• mdash: em-dash

• ndash: en-dash

• laquo: left guillemet

• raquo: right guillemet

• laquo_space: left guillemet followed by a space

• raquo_space: right guillemet preceeded by a space

Default: {} Used by: HTML/Latex converter

EXIT STATUS

       The exit status is 0 if no error happened. Otherwise it is 1.

AUTHOR

       kramdown was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .

       This manual page was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .

                                          November 2016                               KRAMDOWN(1)

NAME

SYNOPSIS

DESCRIPTION

CLI-ONLY OPTIONS

KRAMDOWN OPTIONS

EXIT STATUS

SEE ALSO

AUTHOR