KRAMDOWN(1) General Commands Manual KRAMDOWN(1)
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, or html. The input format GFM
is available through the kramdown-parser-gfm gem.
-o FORMAT, --output FORMAT
Specify one or more output formats separated by commas: html
(default), kramdown, latex, man or remove_html_tags. The
converter pdf is available through the kramdown-converter-pdf
gem.
-x EXT, --extension EXT
Load one or more extensions. The name of the extension should
not include the kramdown- prefix, e.g. just parser-gfm. Multiple
extensions can be loaded by separating them with commas.
Note: This option has to be used before any other options that
rely on the extension already being loaded.
--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
--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-link-text ARG
The text used for the footnote number in a footnote link
This option can be used to add additional text to the footnote
link. It should be a format string, and is passed the footnote
number as the only argument to the format string. e.g.
"[footnote %s]" would display as "[footnote 1]".
Default: `%s' Used by: HTML
--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
--footnote-prefix ARG
Prefix used for footnote IDs
This option can be used to set a prefix for footnote IDs. This
is useful when rendering multiple documents into the same output
file to avoid duplicate IDs. The prefix should only contain
characters that are valid in an ID!
Default: `' Used by: HTML
--forbidden-inline-options ARG
Defines the options that may not be set using the {::options}
extension
The value needs to be an array of option names.
Default: [template] Used by: HTML converter
--[no-]header-links
Adds anchor tags within headers that can be used to generate
permalinks when not using a table of contents.
The anchor tags are empty, but can be styled to your liking.
Default: false
--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 hallo 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
--list-indent ARG
Sets the number of spaces to use for list indentation
Default: 2 Used by: Kramdown converter
--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-line-breaks-for-cjk
Specifies whether line breaks should be removed between CJK
characters
Default: false Used by: HTML 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: rouge 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:
o hellip: ellipsis
o mdash: em-dash
o ndash: en-dash
o laquo: left guillemet
o raquo: right guillemet
o laquo_space: left guillemet followed by a space
o 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.
SEE ALSO
The kramdown website for more
information, especially on the supported input syntax.
AUTHOR
kramdown was written by Thomas Leitner .
This manual page was written by Thomas Leitner .
January 2019 KRAMDOWN(1)