xenial (1) kramdown.1.gz

Provided by: ruby-kramdown_1.10.0-1_all bug

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.

OPTIONS

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

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

       -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

       --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

       --[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

EXIT STATUS

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

SEE ALSO

       The  kramdown  website,  http://kramdown.gettalong.org/ for more information, especially on the supported
       input syntax.

AUTHOR

       kramdown was written by Thomas Leitner <t_leitner@gmx.at>.

       This manual page was written by Thomas Leitner <t_leitner@gmx.at>.

                                                  February 2015                                      KRAMDOWN(1)