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, or html. The input  format  GFM
38              is available through the kramdown-parser-gfm gem.
39
40       -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
45       -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
50              Note:  This  option has to be used before any other options that
51              rely on the extension already being loaded.
52
53       --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
57       --config-file FILE
58              Override the default path and name of the configuration file.
59
60       -v, --version
61              Show the version of kramdown.
62
63       -h, --help
64              Show the help.
65

KRAMDOWN OPTIONS

67       --auto-id-prefix ARG
68              Prefix used for automatically generated header IDs
69
70              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
75              Default: ‘’ Used by: HTML/Latex converter
76
77       --[no-]auto-id-stripping
78              Strip all formatting from header text for automatic  ID  genera‐
79              tion
80
81              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
85              This  option will be removed in version 2.0 because this will be
86              the default then.
87
88              Default: false Used by: kramdown parser
89
90       --[no-]auto-ids
91              Use automatic header ID generation
92
93              If this option is true, ID values for all headers are  automati‐
94              cally generated if no ID is explicitly specified.
95
96              Default: true Used by: HTML/Latex converter
97
98       --entity-output ARG
99              Defines how entities are output
100
101              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
107              Default: :as_char Used by: HTML converter, kramdown converter
108
109       --footnote-backlink ARG
110              Defines the text that should be used for the footnote backlinks
111
112              The  footnote backlink is just text, so any special HTML charac‐
113              ters will be escaped.
114
115              If the footnote backlint text is an empty  string,  no  footnote
116              backlinks will be generated.
117
118              Default: ‘8617;’ Used by: HTML converter
119
120       --[no-]footnote-backlink-inline
121              Specifies whether the footnote backlink should always be inline
122
123              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
127              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
132              Default: false Used by: HTML converter
133
134       --footnote-nr ARG
135              The number of the first footnote
136
137              This option can be used to specify the number that is  used  for
138              the first footnote.
139
140              Default: 1 Used by: HTML converter
141
142       --footnote-prefix ARG
143              Prefix used for footnote IDs
144
145              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
150              Default: ‘’ Used by: HTML
151
152       --header-offset ARG
153              Sets the output offset for headers
154
155              If this option is c (may also be negative) then  a  header  with
156              level  n  will  be  output as a header with level c+n. If c+n is
157              lower than 1, level 1 will be used. If c+n is  greater  than  6,
158              level 6 will be used.
159
160              Default:  0  Used  by: HTML converter, Kramdown converter, Latex
161              converter
162
163       --[no-]html-to-native
164              Convert HTML elements to native elements
165
166              If this option is true, the parser  converts  HTML  elements  to
167              native  elements.  For  example, when parsing <em>hallo</em> the
168              emphasis tag would normally be converted  to  an  :html  element
169              with  tag type :em. If html_to_native is true, then the emphasis
170              would be converted to a native :em element.
171
172              This is useful for converters that cannot deal  with  HTML  ele‐
173              ments.
174
175              Default: false Used by: kramdown parser
176
177       --latex-headers ARG
178              Defines the LaTeX commands for different header levels
179
180              The  commands  for the header levels one to six can be specified
181              by separating them with commas.
182
183              Default:     section,subsection,subsubsection,paragraph,subpara‐
184              graph,subparagraph Used by: Latex converter
185
186       --line-width ARG
187              Defines the line width to be used when outputting a document
188
189              Default: 72 Used by: kramdown converter
190
191       --link-defs ARG
192              Pre-defines link definitions
193
194              This  option  can  be  used  to pre-define link definitions. The
195              value needs to be a Hash where the keys are the link identifiers
196              and  the values are two element Arrays with the link URL and the
197              link title.
198
199              If the value is a String, it has to contain a  valid  YAML  hash
200              and the hash has to follow the above guidelines.
201
202              Default: {} Used by: kramdown parser
203
204       --math-engine ARG
205              Set the math engine
206
207              Specifies  the  math  engine  that should be used for converting
208              math blocks/spans. If this option  is  set  to  +nil+,  no  math
209              engine is used and the math blocks/spans are output as is.
210
211              Options  for  the  selected  math  engine  can  be  set with the
212              math_engine_opts configuration option.
213
214              Default: mathjax Used by: HTML converter
215
216       --math-engine-opts ARG
217              Set the math engine options
218
219              Specifies options for the math engine set  via  the  math_engine
220              configuration option.
221
222              The  value  needs  to  be  a  hash with key-value pairs that are
223              understood by the used math engine.
224
225              Default: {} Used by: HTML converter
226
227       --[no-]parse-block-html
228              Process kramdown syntax in block HTML tags
229
230              If this option is true, the kramdown parser processes  the  con‐
231              tent of block HTML tags as text containing block-level elements.
232              Since this is not wanted normally, the default is false.  It  is
233              normally  better  to  selectively enable kramdown processing via
234              the markdown attribute.
235
236              Default: false Used by: kramdown parser
237
238       --[no-]parse-span-html
239              Process kramdown syntax in span HTML tags
240
241              If this option is true, the kramdown parser processes  the  con‐
242              tent of span HTML tags as text containing span-level elements.
243
244              Default: true Used by: kramdown parser
245
246       --[no-]remove-block-html-tags
247              Remove block HTML tags
248
249              If  this  option  is  true, the RemoveHtmlTags converter removes
250              block HTML tags.
251
252              Default: true Used by: RemoveHtmlTags converter
253
254       --[no-]remove-line-breaks-for-cjk
255              Specifies whether line breaks  should  be  removed  between  CJK
256              characters
257
258              Default: false Used by: HTML converter
259
260       --[no-]remove-span-html-tags
261              Remove span HTML tags
262
263              If  this  option  is  true, the RemoveHtmlTags converter removes
264              span HTML tags.
265
266              Default: false Used by: RemoveHtmlTags converter
267
268       --smart-quotes ARG
269              Defines the HTML entity names or code  points  for  smart  quote
270              output
271
272              The entities identified by entity name or code point that should
273              be used for, in order, a  left  single  quote,  a  right  single
274              quote,  a  left double and a right double quote are specified by
275              separating them with commas.
276
277              Default: lsquo,rsquo,ldquo,rdquo Used by: HTML/Latex converter
278
279       --syntax-highlighter ARG
280              Set the syntax highlighter
281
282              Specifies the syntax highlighter that should be used  for  high‐
283              lighting  code blocks and spans. If this option is set to +nil+,
284              no syntax highlighting is done.
285
286              Options for the syntax highlighter can  be  set  with  the  syn‐
287              tax_highlighter_opts configuration option.
288
289              Default: rouge Used by: HTML/Latex converter
290
291       --syntax-highlighter-opts ARG
292              Set the syntax highlighter options
293
294              Specifies  options  for  the syntax highlighter set via the syn‐
295              tax_highlighter configuration option.
296
297              The value needs to be a  hash  with  key-value  pairs  that  are
298              understood by the used syntax highlighter.
299
300              Default: {} Used by: HTML/Latex converter
301
302       --template ARG
303              The name of an ERB template file that should be used to wrap the
304              output or the ERB template itself.
305
306              This is used to wrap the output in an environment  so  that  the
307              output  can  be  used as a stand-alone document. For example, an
308              HTML template would provide the needed header and body  tags  so
309              that  the  whole  output is a valid HTML file. If no template is
310              specified, the output will be just the converted text.
311
312              When resolving the template file, the  given  template  name  is
313              used first. If such a file is not found, the converter extension
314              (the same as the converter name) is appended. If the file  still
315              cannot be found, the templates name is interpreted as a template
316              name that is provided by kramdown (without the converter  exten‐
317              sion).  If  the  file  is  still not found, the template name is
318              checked if it starts with ‘string://’ and if it does, this  pre‐
319              fix is removed and the rest is used as template content.
320
321              kramdown  provides  a default template named ‘document’ for each
322              converter.
323
324              Default: ‘’ Used by: all converters
325
326       --toc-levels ARG
327              Defines the levels that are used for the table of contents
328
329              The individual levels can be specified by separating  them  with
330              commas  (e.g.  1,2,3)  or by using the range syntax (e.g. 1..3).
331              Only the specified levels are used for the table of contents.
332
333              Default: 1..6 Used by: HTML/Latex converter
334
335       --[no-]transliterated-header-ids
336              Transliterate the header text before generating the ID
337
338              Only ASCII characters are used in headers IDs. This is not  good
339              for  languages  with many non-ASCII characters. By enabling this
340              option the header text is transliterated to  ASCII  as  good  as
341              possible so that the resulting header ID is more useful.
342
343              The  stringex  library needs to be installed for this feature to
344              work!
345
346              Default: false Used by: HTML/Latex converter
347
348       --typographic-symbols ARG
349              Defines a mapping from typographical symbol to output characters
350
351              Typographical symbols are normally output using their equivalent
352              Unicode  codepoint.  However,  sometimes one wants to change the
353              output, mostly to fallback to a sequence of ASCII characters.
354
355              This option allows this by specifying a mapping from typographi‐
356              cal  symbol to its output string. For example, the mapping {hel‐
357              lip: ...} would output the standard ASCII representation  of  an
358              ellipsis.
359
360              The available typographical symbol names are:
361
362              ·   hellip: ellipsis
363
364              ·   mdash: em-dash
365
366              ·   ndash: en-dash
367
368              ·   laquo: left guillemet
369
370              ·   raquo: right guillemet
371
372              ·   laquo_space: left guillemet followed by a space
373
374              ·   raquo_space: right guillemet preceeded by a space
375
376              Default: {} Used by: HTML/Latex converter
377

EXIT STATUS

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

SEE ALSO

382       The  kramdown website ⟨http://kramdown.gettalong.org⟩ for more informa‐
383       tion, especially on the supported input syntax.
384

AUTHOR

386       kramdown was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .
387
388       This manual page was written by Thomas Leitner ⟨t_leitner@gmx.at⟩ .
389
390
391
392                                 January 2019                      KRAMDOWN(1)
Impressum