.TH "KRAMDOWN" 1 "February 2015"
.SH NAME
kramdown \- a fast, pure-Ruby Markdown-superset converter
.SH SYNOPSIS
.B kramdown
[\fIoptions\fR]
[\fIFILE\fR ...]
.SH 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 \fIFILE\fR 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.
.SH OPTIONS
.TP
.B \-i, \-\-input ARG
Specify the input format. Available input formats: kramdown (this is the default), markdown, GFM or html.
.TP
.B \-o, \-\-output ARG
Specify one or more output formats separated by commas: html (default), kramdown, latex, pdf or
remove_html_tags.
.TP
.B \-v, \-\-version
Show the version of kramdown.
.TP
.B \-h, \-\-help
Show the help.

.SH KRAMDOWN OPTIONS

.TP
.B \-\-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


.TP
.B \-\-[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


.TP
.B \-\-[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


.TP
.B \-\-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


.TP
.B \-\-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


.TP
.B \-\-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


.TP
.B \-\-coderay-line-number-start ARG

The start value for the line numbers

Default: 1
Used by: HTML converter


.TP
.B \-\-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


.TP
.B \-\-coderay-tab-width ARG

The tab width used in highlighted code

Used by: HTML converter


.TP
.B \-\-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


.TP
.B \-\-[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


.TP
.B \-\-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


.TP
.B \-\-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.

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


.TP
.B \-\-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


.TP
.B \-\-[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


.TP
.B \-\-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


.TP
.B \-\-[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


.TP
.B \-\-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


.TP
.B \-\-line-width ARG

Defines the line width to be used when outputting a document

Default: 72
Used by: kramdown converter


.TP
.B \-\-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


.TP
.B \-\-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


.TP
.B \-\-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


.TP
.B \-\-[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


.TP
.B \-\-[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


.TP
.B \-\-[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


.TP
.B \-\-[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


.TP
.B \-\-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


.TP
.B \-\-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


.TP
.B \-\-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


.TP
.B \-\-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


.TP
.B \-\-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


.TP
.B \-\-[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


.SH EXIT STATUS
The exit status is 0 if no error happened. Otherwise it is 1.
.SH SEE ALSO
The kramdown website, http://kramdown.gettalong.org/ for more information, especially on the supported
input syntax.
.SH AUTHOR
kramdown was written by Thomas Leitner <t_leitner@gmx.at>.
.PP
This manual page was written by Thomas Leitner <t_leitner@gmx.at>.