1KRAMDOWN(1)                 General Commands Manual                KRAMDOWN(1)
2
3
4

NAME

6       kramdown - a fast, pure-Ruby Markdown-superset converter
7

SYNOPSIS

9       kramdown [options] [FILE...]
10

DESCRIPTION

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
19       If FILE is not specified, kramdown reads from the standard  input.  The
20       result is written to the standard output.
21
22       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
27       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

CLI-ONLY OPTIONS

35       -i FORMAT, --input FORMAT
36              Specify  the  input  format.  Available  input formats: kramdown
37              (this is the default), markdown, GFM or html.
38
39       -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
43       --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
47       --config-file FILE
48              Override the default path and name of the configuration file.
49
50       -v, --version
51              Show the version of kramdown.
52
53       -h, --help
54              Show the help.
55

KRAMDOWN OPTIONS

57       --auto-id-prefix ARG
58              Prefix used for automatically generated header IDs
59
60              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
65              Default: ‘’ Used by: HTML/Latex converter
66
67       --[no-]auto-id-stripping
68              Strip  all  formatting from header text for automatic ID genera‐
69              tion
70
71              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
75              This option will be removed in version 2.0 because this will  be
76              the default then.
77
78              Default: false Used by: kramdown parser
79
80       --[no-]auto-ids
81              Use automatic header ID generation
82
83              If  this option is true, ID values for all headers are automati‐
84              cally generated if no ID is explicitly specified.
85
86              Default: true Used by: HTML/Latex converter
87
88       --coderay-bold-every ARG
89              Defines how often a line number should be made bold
90
91              Can either be an integer or false (to turn off bold line numbers
92              completely).
93
94              Default: 10 Used by: HTML converter
95
96       --coderay-css ARG
97              Defines how the highlighted code gets styled
98
99              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
103              Default: style Used by: HTML converter
104
105       --coderay-default-lang ARG
106              Sets the default language for highlighting code blocks
107
108              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
112              Default: nil Used by: HTML converter
113
114       --coderay-line-number-start ARG
115              The start value for the line numbers
116
117              Default: 1 Used by: HTML converter
118
119       --coderay-line-numbers ARG
120              Defines how and if line numbers should be shown
121
122              The  possible  values are :table, :inline or nil. If this option
123              is nil, no line numbers are shown.
124
125              Default: :inline Used by: HTML converter
126
127       --coderay-tab-width ARG
128              The tab width used in highlighted code
129
130              Used by: HTML converter
131
132       --coderay-wrap ARG
133              Defines how the highlighted code should be wrapped
134
135              The possible values are :span, :div or nil.
136
137              Default: :div Used by: HTML converter
138
139       --[no-]enable-coderay
140              Use coderay for syntax highlighting
141
142              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
146              Default: true Used by: HTML converter
147
148       --entity-output ARG
149              Defines how entities are output
150
151              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
157              Default: :as_char Used by: HTML converter, kramdown converter
158
159       --footnote-backlink ARG
160              Defines the text that should be used for the footnote backlinks
161
162              The footnote backlink is just text, so any special HTML  charac‐
163              ters will be escaped.
164
165              If  the  footnote  backlint text is an empty string, no footnote
166              backlinks will be generated.
167
168              Default: ‘8617;’ Used by: HTML converter
169
170       --[no-]footnote-backlink-inline
171              Specifies whether the footnote backlink should always be inline
172
173              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
177              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
182              Default: false Used by: HTML converter
183
184       --footnote-nr ARG
185              The number of the first footnote
186
187              This  option  can be used to specify the number that is used for
188              the first footnote.
189
190              Default: 1 Used by: HTML converter
191
192       --gfm-quirks ARG
193              Enables a set of GFM specific quirks
194
195              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
199              This option allows one to  enable/disable  certain  GFM  quirks,
200              i.e. ways in which GFM parsing differs from kramdown parsing.
201
202              The  value  has  to  be  a  list  of  quirk names that should be
203              enabled, separated by commas. Possible names are:
204
205              ·   paragraph_end
206
207                  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
211                  Note that if this quirk is used, lazy line wrapping does not
212                  fully work anymore!
213
214              ·   no_auto_typographic
215
216                  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
221              Default: paragraph_end Used by: GFM parser
222
223       --[no-]hard-wrap
224              Interprets line breaks literally
225
226              Insert HTML <br /> tags inside  paragraphs  where  the  original
227              Markdown  document  had  newlines  (by default, Markdown ignores
228              these newlines).
229
230              Default: true Used by: GFM parser
231
232       --header-offset ARG
233              Sets the output offset for headers
234
235              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
240              Default:  0  Used  by: HTML converter, Kramdown converter, Latex
241              converter
242
243       --[no-]html-to-native
244              Convert HTML elements to native elements
245
246              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
252              This is useful for converters that cannot deal  with  HTML  ele‐
253              ments.
254
255              Default: false Used by: kramdown parser
256
257       --latex-headers ARG
258              Defines the LaTeX commands for different header levels
259
260              The  commands  for the header levels one to six can be specified
261              by separating them with commas.
262
263              Default:     section,subsection,subsubsection,paragraph,subpara‐
264              graph,subparagraph Used by: Latex converter
265
266       --line-width ARG
267              Defines the line width to be used when outputting a document
268
269              Default: 72 Used by: kramdown converter
270
271       --link-defs ARG
272              Pre-defines link definitions
273
274              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
279              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
282              Default: {} Used by: kramdown parser
283
284       --math-engine ARG
285              Set the math engine
286
287              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
291              Options  for  the  selected  math  engine  can  be  set with the
292              math_engine_opts configuration option.
293
294              Default: mathjax Used by: HTML converter
295
296       --math-engine-opts ARG
297              Set the math engine options
298
299              Specifies options for the math engine set  via  the  math_engine
300              configuration option.
301
302              The  value  needs  to  be  a  hash with key-value pairs that are
303              understood by the used math engine.
304
305              Default: {} Used by: HTML converter
306
307       --[no-]parse-block-html
308              Process kramdown syntax in block HTML tags
309
310              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
316              Default: false Used by: kramdown parser
317
318       --[no-]parse-span-html
319              Process kramdown syntax in span HTML tags
320
321              If this option is true, the kramdown parser processes  the  con‐
322              tent of span HTML tags as text containing span-level elements.
323
324              Default: true Used by: kramdown parser
325
326       --[no-]remove-block-html-tags
327              Remove block HTML tags
328
329              If  this  option  is  true, the RemoveHtmlTags converter removes
330              block HTML tags.
331
332              Default: true Used by: RemoveHtmlTags converter
333
334       --[no-]remove-span-html-tags
335              Remove span HTML tags
336
337              If this option is true,  the  RemoveHtmlTags  converter  removes
338              span HTML tags.
339
340              Default: false Used by: RemoveHtmlTags converter
341
342       --smart-quotes ARG
343              Defines  the  HTML  entity  names or code points for smart quote
344              output
345
346              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
351              Default: lsquo,rsquo,ldquo,rdquo Used by: HTML/Latex converter
352
353       --syntax-highlighter ARG
354              Set the syntax highlighter
355
356              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
360              Options  for  the  syntax  highlighter  can be set with the syn‐
361              tax_highlighter_opts configuration option.
362
363              Default: coderay Used by: HTML/Latex converter
364
365       --syntax-highlighter-opts ARG
366              Set the syntax highlighter options
367
368              Specifies options for the syntax highlighter set  via  the  syn‐
369              tax_highlighter configuration option.
370
371              The  value  needs  to  be  a  hash with key-value pairs that are
372              understood by the used syntax highlighter.
373
374              Default: {} Used by: HTML/Latex converter
375
376       --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
380              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
386              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
395              kramdown provides a default template named ‘document’  for  each
396              converter.
397
398              Default: ‘’ Used by: all converters
399
400       --toc-levels ARG
401              Defines the levels that are used for the table of contents
402
403              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
407              Default: 1..6 Used by: HTML/Latex converter
408
409       --[no-]transliterated-header-ids
410              Transliterate the header text before generating the ID
411
412              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
417              The stringex library needs to be installed for this  feature  to
418              work!
419
420              Default: false Used by: HTML/Latex converter
421
422       --typographic-symbols ARG
423              Defines a mapping from typographical symbol to output characters
424
425              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
429              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
434              The available typographical symbol names are:
435
436              ·   hellip: ellipsis
437
438              ·   mdash: em-dash
439
440              ·   ndash: en-dash
441
442              ·   laquo: left guillemet
443
444              ·   raquo: right guillemet
445
446              ·   laquo_space: left guillemet followed by a space
447
448              ·   raquo_space: right guillemet preceeded by a space
449
450              Default: {} Used by: HTML/Latex converter
451

EXIT STATUS

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

SEE ALSO

456       The kramdown website ⟨http://kramdown.gettalong.org⟩ for more  informa‐
457       tion, especially on the supported input syntax.
458

AUTHOR

460       kramdown was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .
461
462       This manual page was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .
463
464
465
466                                 November 2016                     KRAMDOWN(1)
Impressum