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 in‐
23 cludes the options that are used directly by the kramdown binary. The
24 second set of options controls how kramdown parses and converts its in‐
25 put.
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, or html. The input format GFM
38 is available through the kramdown-parser-gfm gem.
39 -o FORMAT, --output FORMAT
41 Specify one or more output formats separated by commas: html
42 (default), kramdown, latex, man or remove_html_tags. The con‐
43 verter pdf is available through the kramdown-converter-pdf gem.
44 -x EXT, --extension EXT
46 Load one or more extensions. The name of the extension should
47 not include the kramdown- prefix, e.g. just parser-gfm. Multiple
48 extensions can be loaded by separating them with commas.
49 Note: This option has to be used before any other options that
51 rely on the extension already being loaded.
52 --no-config-file
54 Do not read any configuration file. Default behavior is to check
55 for a configuration file and read it if it exists.
56 --config-file FILE
58 Override the default path and name of the configuration file.
59 -v, --version
61 Show the version of kramdown.
62 -h, --help
64 Show the help.
65
67 --auto-id-prefix ARG
68 Prefix used for automatically generated header IDs
69 This option can be used to set a prefix for the automatically
71 generated header IDs so that there is no conflict when rendering
72 multiple kramdown documents into one output file separately. The
73 prefix should only contain characters that are valid in an ID!
74 Default: ‘’ Used by: HTML/Latex converter
76 --[no-]auto-id-stripping
78 Strip all formatting from header text for automatic ID genera‐
79 tion
80 If this option is true, only the text elements of a header are
82 used for generating the ID later (in contrast to just using the
83 raw header text line).
84 This option will be removed in version 2.0 because this will be
86 the default then.
87 Default: false Used by: kramdown parser
89 --[no-]auto-ids
91 Use automatic header ID generation
92 If this option is true, ID values for all headers are automati‐
94 cally generated if no ID is explicitly specified.
95 Default: true Used by: HTML/Latex converter
97 --entity-output ARG
99 Defines how entities are output
100 The possible values are :as_input (entities are output in the
102 same form as found in the input), :numeric (entities are output
103 in numeric form), :symbolic (entities are output in symbolic
104 form if possible) or :as_char (entities are output as characters
105 if possible, only available on Ruby 1.9).
106 Default: :as_char Used by: HTML converter, kramdown converter
108 --footnote-backlink ARG
110 Defines the text that should be used for the footnote backlinks
111 The footnote backlink is just text, so any special HTML charac‐
113 ters will be escaped.
114 If the footnote backlint text is an empty string, no footnote
116 backlinks will be generated.
117 Default: ‘8617;’ Used by: HTML converter
119 --[no-]footnote-backlink-inline
121 Specifies whether the footnote backlink should always be inline
122 With the default of false the footnote backlink is placed at the
124 end of the last paragraph if there is one, or an extra paragraph
125 with only the footnote backlink is created.
126 Setting this option to true tries to place the footnote backlink
128 in the last, possibly nested paragraph or header. If this fails
129 (e.g. in the case of a table), an extra paragraph with only the
130 footnote backlink is created.
131 Default: false Used by: HTML converter
133 --footnote-nr ARG
135 The number of the first footnote
136 This option can be used to specify the number that is used for
138 the first footnote.
139 Default: 1 Used by: HTML converter
141 --footnote-prefix ARG
143 Prefix used for footnote IDs
144 This option can be used to set a prefix for footnote IDs. This
146 is useful when rendering multiple documents into the same output
147 file to avoid duplicate IDs. The prefix should only contain
148 characters that are valid in an ID!
149 Default: ‘’ Used by: HTML
151 --forbidden-inline-options ARG
153 Defines the options that may not be set using the {::options}
154 extension
155 The value needs to be an array of option names.
157 Default: [template] Used by: HTML converter
159 --header-offset ARG
161 Sets the output offset for headers
162 If this option is c (may also be negative) then a header with
164 level n will be output as a header with level c+n. If c+n is
165 lower than 1, level 1 will be used. If c+n is greater than 6,
166 level 6 will be used.
167 Default: 0 Used by: HTML converter, Kramdown converter, Latex
169 converter
170 --[no-]html-to-native
172 Convert HTML elements to native elements
173 If this option is true, the parser converts HTML elements to na‐
175 tive elements. For example, when parsing <em>hallo</em> the em‐
176 phasis tag would normally be converted to an :html element with
177 tag type :em. If html_to_native is true, then the emphasis would
178 be converted to a native :em element.
179 This is useful for converters that cannot deal with HTML ele‐
181 ments.
182 Default: false Used by: kramdown parser
184 --latex-headers ARG
186 Defines the LaTeX commands for different header levels
187 The commands for the header levels one to six can be specified
189 by separating them with commas.
190 Default: section,subsection,subsubsection,paragraph,subpara‐
192 graph,subparagraph Used by: Latex converter
193 --line-width ARG
195 Defines the line width to be used when outputting a document
196 Default: 72 Used by: kramdown converter
198 --link-defs ARG
200 Pre-defines link definitions
201 This option can be used to pre-define link definitions. The
203 value needs to be a Hash where the keys are the link identifiers
204 and the values are two element Arrays with the link URL and the
205 link title.
206 If the value is a String, it has to contain a valid YAML hash
208 and the hash has to follow the above guidelines.
209 Default: {} Used by: kramdown parser
211 --list-indent ARG
213 Sets the number of spaces to use for list indentation
214 Default: 2 Used by: Kramdown converter
216 --math-engine ARG
218 Set the math engine
219 Specifies the math engine that should be used for converting
221 math blocks/spans. If this option is set to +nil+, no math en‐
222 gine is used and the math blocks/spans are output as is.
223 Options for the selected math engine can be set with the
225 math_engine_opts configuration option.
226 Default: mathjax Used by: HTML converter
228 --math-engine-opts ARG
230 Set the math engine options
231 Specifies options for the math engine set via the math_engine
233 configuration option.
234 The value needs to be a hash with key-value pairs that are un‐
236 derstood by the used math engine.
237 Default: {} Used by: HTML converter
239 --[no-]parse-block-html
241 Process kramdown syntax in block HTML tags
242 If this option is true, the kramdown parser processes the con‐
244 tent of block HTML tags as text containing block-level elements.
245 Since this is not wanted normally, the default is false. It is
246 normally better to selectively enable kramdown processing via
247 the markdown attribute.
248 Default: false Used by: kramdown parser
250 --[no-]parse-span-html
252 Process kramdown syntax in span HTML tags
253 If this option is true, the kramdown parser processes the con‐
255 tent of span HTML tags as text containing span-level elements.
256 Default: true Used by: kramdown parser
258 --[no-]remove-block-html-tags
260 Remove block HTML tags
261 If this option is true, the RemoveHtmlTags converter removes
263 block HTML tags.
264 Default: true Used by: RemoveHtmlTags converter
266 --[no-]remove-line-breaks-for-cjk
268 Specifies whether line breaks should be removed between CJK
269 characters
270 Default: false Used by: HTML converter
272 --[no-]remove-span-html-tags
274 Remove span HTML tags
275 If this option is true, the RemoveHtmlTags converter removes
277 span HTML tags.
278 Default: false Used by: RemoveHtmlTags converter
280 --smart-quotes ARG
282 Defines the HTML entity names or code points for smart quote
283 output
284 The entities identified by entity name or code point that should
286 be used for, in order, a left single quote, a right single
287 quote, a left double and a right double quote are specified by
288 separating them with commas.
289 Default: lsquo,rsquo,ldquo,rdquo Used by: HTML/Latex converter
291 --syntax-highlighter ARG
293 Set the syntax highlighter
294 Specifies the syntax highlighter that should be used for high‐
296 lighting code blocks and spans. If this option is set to +nil+,
297 no syntax highlighting is done.
298 Options for the syntax highlighter can be set with the syn‐
300 tax_highlighter_opts configuration option.
301 Default: rouge Used by: HTML/Latex converter
303 --syntax-highlighter-opts ARG
305 Set the syntax highlighter options
306 Specifies options for the syntax highlighter set via the syn‐
308 tax_highlighter configuration option.
309 The value needs to be a hash with key-value pairs that are un‐
311 derstood by the used syntax highlighter.
312 Default: {} Used by: HTML/Latex converter
314 --template ARG
316 The name of an ERB template file that should be used to wrap the
317 output or the ERB template itself.
318 This is used to wrap the output in an environment so that the
320 output can be used as a stand-alone document. For example, an
321 HTML template would provide the needed header and body tags so
322 that the whole output is a valid HTML file. If no template is
323 specified, the output will be just the converted text.
324 When resolving the template file, the given template name is
326 used first. If such a file is not found, the converter extension
327 (the same as the converter name) is appended. If the file still
328 cannot be found, the templates name is interpreted as a template
329 name that is provided by kramdown (without the converter exten‐
330 sion). If the file is still not found, the template name is
331 checked if it starts with ‘string://’ and if it does, this pre‐
332 fix is removed and the rest is used as template content.
333 kramdown provides a default template named ‘document’ for each
335 converter.
336 Default: ‘’ Used by: all converters
338 --toc-levels ARG
340 Defines the levels that are used for the table of contents
341 The individual levels can be specified by separating them with
343 commas (e.g. 1,2,3) or by using the range syntax (e.g. 1..3).
344 Only the specified levels are used for the table of contents.
345 Default: 1..6 Used by: HTML/Latex converter
347 --[no-]transliterated-header-ids
349 Transliterate the header text before generating the ID
350 Only ASCII characters are used in headers IDs. This is not good
352 for languages with many non-ASCII characters. By enabling this
353 option the header text is transliterated to ASCII as good as
354 possible so that the resulting header ID is more useful.
355 The stringex library needs to be installed for this feature to
357 work!
358 Default: false Used by: HTML/Latex converter
360 --typographic-symbols ARG
362 Defines a mapping from typographical symbol to output characters
363 Typographical symbols are normally output using their equivalent
365 Unicode codepoint. However, sometimes one wants to change the
366 output, mostly to fallback to a sequence of ASCII characters.
367 This option allows this by specifying a mapping from typographi‐
369 cal symbol to its output string. For example, the mapping {hel‐
370 lip: ...} would output the standard ASCII representation of an
371 ellipsis.
372 The available typographical symbol names are:
374 • hellip: ellipsis
376 • mdash: em-dash
378 • ndash: en-dash
380 • laquo: left guillemet
382 • raquo: right guillemet
384 • laquo_space: left guillemet followed by a space
386 • raquo_space: right guillemet preceeded by a space
388 Default: {} Used by: HTML/Latex converter
390
392 The exit status is 0 if no error happened. Otherwise it is 1.
393
395 The kramdown website ⟨http://kramdown.gettalong.org⟩ for more informa‐
396 tion, especially on the supported input syntax.
397
399 kramdown was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .
400 This manual page was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .
402 January 2019 KRAMDOWN(1)