1KRAMDOWN(1) General Commands Manual KRAMDOWN(1)
2
6 kramdown - a fast, pure-Ruby Markdown-superset converter
7
9 kramdown [options] [FILE...]
10
12 kramdown is primarily used for parsing a superset of Markdown and con‐
13 verting it to different output formats. It supports standard Markdown
14 (with some minor modifications) and various extensions like tables and
15 definition lists. Due to its modular architecture it also allows other
16 input formats than Markdown, for example, HTML or Github Flavored Mark‐
17 down.
18 If FILE is not specified, kramdown reads from the standard input. The
20 result is written to the standard output.
21 There are two sets of options that kramdown accepts: The first one
23 includes the options that are used directly by the kramdown binary. The
24 second set of options controls how kramdown parses and converts its
25 input.
26 Default values for this second set can be set using YAML via the con‐
28 figuration file kramdownrc. Note that configuration option names use
29 underscores, not dashes (dashes are just used in the CLI options
30 names), and boolean options do not have a no variant but a value of
31 true or false. This file has to be in XDG_CONFIG_HOME on Linux/Unix,
32 ~/Library/Preferences on macOS and ~/AppData/Local on Windows.
33
35 -i FORMAT, --input FORMAT
36 Specify the input format. Available input formats: kramdown
37 (this is the default), markdown, GFM or html.
38 -o FORMAT, --output FORMAT
40 Specify one or more output formats separated by commas: html
41 (default), kramdown, latex, pdf, man or remove_html_tags.
42 --no-config-file
44 Do not read any configuration file. Default behavior is to check
45 for a configuration file and read it if it exists.
46 --config-file FILE
48 Override the default path and name of the configuration file.
49 -v, --version
51 Show the version of kramdown.
52 -h, --help
54 Show the help.
55
57 --auto-id-prefix ARG
58 Prefix used for automatically generated header IDs
59 This option can be used to set a prefix for the automatically
61 generated header IDs so that there is no conflict when rendering
62 multiple kramdown documents into one output file separately. The
63 prefix should only contain characters that are valid in an ID!
64 Default: ‘’ Used by: HTML/Latex converter
66 --[no-]auto-id-stripping
68 Strip all formatting from header text for automatic ID genera‐
69 tion
70 If this option is true, only the text elements of a header are
72 used for generating the ID later (in contrast to just using the
73 raw header text line).
74 This option will be removed in version 2.0 because this will be
76 the default then.
77 Default: false Used by: kramdown parser
79 --[no-]auto-ids
81 Use automatic header ID generation
82 If this option is true, ID values for all headers are automati‐
84 cally generated if no ID is explicitly specified.
85 Default: true Used by: HTML/Latex converter
87 --coderay-bold-every ARG
89 Defines how often a line number should be made bold
90 Can either be an integer or false (to turn off bold line numbers
92 completely).
93 Default: 10 Used by: HTML converter
95 --coderay-css ARG
97 Defines how the highlighted code gets styled
98 Possible values are :class (CSS classes are applied to the code
100 elements, one must supply the needed CSS file) or :style
101 (default CSS styles are directly applied to the code elements).
102 Default: style Used by: HTML converter
104 --coderay-default-lang ARG
106 Sets the default language for highlighting code blocks
107 If no language is set for a code block, the default language is
109 used instead. The value has to be one of the languages supported
110 by coderay or nil if no default language should be used.
111 Default: nil Used by: HTML converter
113 --coderay-line-number-start ARG
115 The start value for the line numbers
116 Default: 1 Used by: HTML converter
118 --coderay-line-numbers ARG
120 Defines how and if line numbers should be shown
121 The possible values are :table, :inline or nil. If this option
123 is nil, no line numbers are shown.
124 Default: :inline Used by: HTML converter
126 --coderay-tab-width ARG
128 The tab width used in highlighted code
129 Used by: HTML converter
131 --coderay-wrap ARG
133 Defines how the highlighted code should be wrapped
134 The possible values are :span, :div or nil.
136 Default: :div Used by: HTML converter
138 --[no-]enable-coderay
140 Use coderay for syntax highlighting
141 If this option is true, coderay is used by the HTML converter
143 for syntax highlighting the content of code spans and code
144 blocks.
145 Default: true Used by: HTML converter
147 --entity-output ARG
149 Defines how entities are output
150 The possible values are :as_input (entities are output in the
152 same form as found in the input), :numeric (entities are output
153 in numeric form), :symbolic (entities are output in symbolic
154 form if possible) or :as_char (entities are output as characters
155 if possible, only available on Ruby 1.9).
156 Default: :as_char Used by: HTML converter, kramdown converter
158 --footnote-backlink ARG
160 Defines the text that should be used for the footnote backlinks
161 The footnote backlink is just text, so any special HTML charac‐
163 ters will be escaped.
164 If the footnote backlint text is an empty string, no footnote
166 backlinks will be generated.
167 Default: ‘8617;’ Used by: HTML converter
169 --[no-]footnote-backlink-inline
171 Specifies whether the footnote backlink should always be inline
172 With the default of false the footnote backlink is placed at the
174 end of the last paragraph if there is one, or an extra paragraph
175 with only the footnote backlink is created.
176 Setting this option to true tries to place the footnote backlink
178 in the last, possibly nested paragraph or header. If this fails
179 (e.g. in the case of a table), an extra paragraph with only the
180 footnote backlink is created.
181 Default: false Used by: HTML converter
183 --footnote-nr ARG
185 The number of the first footnote
186 This option can be used to specify the number that is used for
188 the first footnote.
189 Default: 1 Used by: HTML converter
191 --gfm-quirks ARG
193 Enables a set of GFM specific quirks
194 The way how GFM is transformed on Github often differs from the
196 way kramdown does things. Many of these differences are negligi‐
197 ble but others are not.
198 This option allows one to enable/disable certain GFM quirks,
200 i.e. ways in which GFM parsing differs from kramdown parsing.
201 The value has to be a list of quirk names that should be
203 enabled, separated by commas. Possible names are:
204 · paragraph_end
206 Disables the kramdown restriction that at least one blank
208 line has to be used after a paragraph before a new block
209 element can be started.
210 Note that if this quirk is used, lazy line wrapping does not
212 fully work anymore!
213 · no_auto_typographic
215 Disables automatic conversion of some characters into their
217 corresponding typographic symbols (like -- to em-dash etc).
218 This helps to achieve results closer to what GitHub Flavored
219 Markdown produces.
220 Default: paragraph_end Used by: GFM parser
222 --[no-]hard-wrap
224 Interprets line breaks literally
225 Insert HTML <br /> tags inside paragraphs where the original
227 Markdown document had newlines (by default, Markdown ignores
228 these newlines).
229 Default: true Used by: GFM parser
231 --header-offset ARG
233 Sets the output offset for headers
234 If this option is c (may also be negative) then a header with
236 level n will be output as a header with level c+n. If c+n is
237 lower than 1, level 1 will be used. If c+n is greater than 6,
238 level 6 will be used.
239 Default: 0 Used by: HTML converter, Kramdown converter, Latex
241 converter
242 --[no-]html-to-native
244 Convert HTML elements to native elements
245 If this option is true, the parser converts HTML elements to
247 native elements. For example, when parsing <em>hallo</em> the
248 emphasis tag would normally be converted to an :html element
249 with tag type :em. If html_to_native is true, then the emphasis
250 would be converted to a native :em element.
251 This is useful for converters that cannot deal with HTML ele‐
253 ments.
254 Default: false Used by: kramdown parser
256 --latex-headers ARG
258 Defines the LaTeX commands for different header levels
259 The commands for the header levels one to six can be specified
261 by separating them with commas.
262 Default: section,subsection,subsubsection,paragraph,subpara‐
264 graph,subparagraph Used by: Latex converter
265 --line-width ARG
267 Defines the line width to be used when outputting a document
268 Default: 72 Used by: kramdown converter
270 --link-defs ARG
272 Pre-defines link definitions
273 This option can be used to pre-define link definitions. The
275 value needs to be a Hash where the keys are the link identifiers
276 and the values are two element Arrays with the link URL and the
277 link title.
278 If the value is a String, it has to contain a valid YAML hash
280 and the hash has to follow the above guidelines.
281 Default: {} Used by: kramdown parser
283 --math-engine ARG
285 Set the math engine
286 Specifies the math engine that should be used for converting
288 math blocks/spans. If this option is set to +nil+, no math
289 engine is used and the math blocks/spans are output as is.
290 Options for the selected math engine can be set with the
292 math_engine_opts configuration option.
293 Default: mathjax Used by: HTML converter
295 --math-engine-opts ARG
297 Set the math engine options
298 Specifies options for the math engine set via the math_engine
300 configuration option.
301 The value needs to be a hash with key-value pairs that are
303 understood by the used math engine.
304 Default: {} Used by: HTML converter
306 --[no-]parse-block-html
308 Process kramdown syntax in block HTML tags
309 If this option is true, the kramdown parser processes the con‐
311 tent of block HTML tags as text containing block-level elements.
312 Since this is not wanted normally, the default is false. It is
313 normally better to selectively enable kramdown processing via
314 the markdown attribute.
315 Default: false Used by: kramdown parser
317 --[no-]parse-span-html
319 Process kramdown syntax in span HTML tags
320 If this option is true, the kramdown parser processes the con‐
322 tent of span HTML tags as text containing span-level elements.
323 Default: true Used by: kramdown parser
325 --[no-]remove-block-html-tags
327 Remove block HTML tags
328 If this option is true, the RemoveHtmlTags converter removes
330 block HTML tags.
331 Default: true Used by: RemoveHtmlTags converter
333 --[no-]remove-span-html-tags
335 Remove span HTML tags
336 If this option is true, the RemoveHtmlTags converter removes
338 span HTML tags.
339 Default: false Used by: RemoveHtmlTags converter
341 --smart-quotes ARG
343 Defines the HTML entity names or code points for smart quote
344 output
345 The entities identified by entity name or code point that should
347 be used for, in order, a left single quote, a right single
348 quote, a left double and a right double quote are specified by
349 separating them with commas.
350 Default: lsquo,rsquo,ldquo,rdquo Used by: HTML/Latex converter
352 --syntax-highlighter ARG
354 Set the syntax highlighter
355 Specifies the syntax highlighter that should be used for high‐
357 lighting code blocks and spans. If this option is set to +nil+,
358 no syntax highlighting is done.
359 Options for the syntax highlighter can be set with the syn‐
361 tax_highlighter_opts configuration option.
362 Default: coderay Used by: HTML/Latex converter
364 --syntax-highlighter-opts ARG
366 Set the syntax highlighter options
367 Specifies options for the syntax highlighter set via the syn‐
369 tax_highlighter configuration option.
370 The value needs to be a hash with key-value pairs that are
372 understood by the used syntax highlighter.
373 Default: {} Used by: HTML/Latex converter
375 --template ARG
377 The name of an ERB template file that should be used to wrap the
378 output or the ERB template itself.
379 This is used to wrap the output in an environment so that the
381 output can be used as a stand-alone document. For example, an
382 HTML template would provide the needed header and body tags so
383 that the whole output is a valid HTML file. If no template is
384 specified, the output will be just the converted text.
385 When resolving the template file, the given template name is
387 used first. If such a file is not found, the converter extension
388 (the same as the converter name) is appended. If the file still
389 cannot be found, the templates name is interpreted as a template
390 name that is provided by kramdown (without the converter exten‐
391 sion). If the file is still not found, the template name is
392 checked if it starts with ‘string://’ and if it does, this pre‐
393 fix is removed and the rest is used as template content.
394 kramdown provides a default template named ‘document’ for each
396 converter.
397 Default: ‘’ Used by: all converters
399 --toc-levels ARG
401 Defines the levels that are used for the table of contents
402 The individual levels can be specified by separating them with
404 commas (e.g. 1,2,3) or by using the range syntax (e.g. 1..3).
405 Only the specified levels are used for the table of contents.
406 Default: 1..6 Used by: HTML/Latex converter
408 --[no-]transliterated-header-ids
410 Transliterate the header text before generating the ID
411 Only ASCII characters are used in headers IDs. This is not good
413 for languages with many non-ASCII characters. By enabling this
414 option the header text is transliterated to ASCII as good as
415 possible so that the resulting header ID is more useful.
416 The stringex library needs to be installed for this feature to
418 work!
419 Default: false Used by: HTML/Latex converter
421 --typographic-symbols ARG
423 Defines a mapping from typographical symbol to output characters
424 Typographical symbols are normally output using their equivalent
426 Unicode codepoint. However, sometimes one wants to change the
427 output, mostly to fallback to a sequence of ASCII characters.
428 This option allows this by specifying a mapping from typographi‐
430 cal symbol to its output string. For example, the mapping {hel‐
431 lip: ...} would output the standard ASCII representation of an
432 ellipsis.
433 The available typographical symbol names are:
435 · hellip: ellipsis
437 · mdash: em-dash
439 · ndash: en-dash
441 · laquo: left guillemet
443 · raquo: right guillemet
445 · laquo_space: left guillemet followed by a space
447 · raquo_space: right guillemet preceeded by a space
449 Default: {} Used by: HTML/Latex converter
451
453 The exit status is 0 if no error happened. Otherwise it is 1.
454
456 The kramdown website ⟨http://kramdown.gettalong.org⟩ for more informa‐
457 tion, especially on the supported input syntax.
458
460 kramdown was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .
461 This manual page was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .
463 November 2016 KRAMDOWN(1)