Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 con-
       verting 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 Mark-
       down.

       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 in-
       cludes the options that are used	directly by the	kramdown  binary.  The
       second set of options controls how kramdown parses and converts its in-
       put.

       Default values for this second set can be set using YAML	via  the  con-
       figuration  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 genera-
	      tion

	      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 automati-
	      cally 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  (de-
	      fault 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  charac-
	      ters 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 negligi-
	      ble 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 en-
	      abled, separated by commas. Possible names are:

	      o	  paragraph_end

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

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

	      o	  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 na-
	      tive  elements. For example, when	parsing	<em>hallo</em> the em-
	      phasis 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  ele-
	      ments.

	      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,subpara-
	      graph,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  en-
	      gine 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 un-
	      derstood 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  con-
	      tent 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  con-
	      tent 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 high-
	      lighting 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 syn-
	      tax_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  syn-
	      tax_highlighter configuration option.

	      The  value  needs	to be a	hash with key-value pairs that are un-
	      derstood 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	exten-
	      sion). If	the file is still not  found,  the  template  name  is
	      checked  if it starts with `string://' and if it does, this pre-
	      fix 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 typographi-
	      cal symbol to its	output string. For example, the	mapping	 {hel-
	      lip:  ...}  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 <http://kramdown.gettalong.org> for	more  informa-
       tion, 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> .

				 November 2016			   KRAMDOWN(1)

NAME | SYNOPSIS | DESCRIPTION | CLI-ONLY OPTIONS | KRAMDOWN OPTIONS | EXIT STATUS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=kramdown&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help