KRAMDOWN(1)

📦
version 2.5.2 · 6 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ KRAMDOWN(1) ✨

okay bestie, come sit, we're doing this 💖 this is the manual page for kramdown, and honestly? it's giving main character energy. everything you'd ever need is in here and we are reading all of it, no skipping, no "tl;dr", we're doing this together 🫶

🌸 NAME 🌸

kramdown — a fast, pure-Ruby Markdown-superset converter ✨

🦋 SYNOPSIS 🦋

kramdown [options] [FILE...]

👑 DESCRIPTION 👑

so, kramdown's whole thing — its literal purpose, its ✨raison d'être✨ — is parsing a superset of Markdown and converting it into different output formats. It's got standard Markdown in there (with a few minor modifications, ngl), plus a whole bunch of extensions like tables and definition lists. And because its architecture is modular — we love a modular queen — it can also take in input formats that aren't Markdown at all, for example HTML or Github Flavored Markdown. versatile icon 💅

If you don't hand it a FILE, kramdown just reads from the standard input. And the result? Goes straight to standard output. easy peasy, no notes.

There are two sets of options that kramdown accepts:

  1. the first one is the options used directly by the kramdown binary 🫡
  2. the second set controls how kramdown parses and converts its input 👑

Default values for that second set? You can set them with YAML, via the configuration file kramdownrc. but okay, listen, some things you need to know, fr fr:

  • configuration option names use underscores, not dashes — dashes are only a thing in the CLI option names
  • boolean options don't have a "no" variant 🚫 — they just take a value of true or false
  • this file has to live in XDG_CONFIG_HOME on Linux/Unix, ~/Library/Preferences on macOS, and ~/AppData/Local on Windows.

💖 CLI-ONLY OPTIONS 💖

these are the ones handled by the binary itself, no cap:

  • -i FORMAT, --input FORMAT — pick your input format 💅 available input formats: kramdown (this is the default, bestie), markdown, or html. And the input format GFM? That one's available through the kramdown-parser-gfm gem ✨
  • -o FORMAT, --output FORMAT — pick one or more output formats, separated by commas: html (default 🥇), kramdown, latex, man, or remove_html_tags. The converter pdf is available through the kramdown-converter-pdf gem.
  • -x EXT, --extension EXT — load one or more extensions 🔌 the name of the extension should not include the kramdown- prefix — like, just parser-gfm, okay? You can load multiple extensions by separating them with commas.
⚠️ Note: this option has to be used before any other options that rely on the extension already being loaded. order matters bestie, it's giving ✨sequence✨
  • --no-config-file — do not read any configuration file 🙈 the 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 🌈

this is the big one. strap in. every single one of these controls how kramdown parses and converts its input 💜

  • --auto-id-prefix ARG — prefix used for automatically generated header IDs 🏷️ this lets you set a prefix on the auto-generated header IDs so there's no conflict when you render 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 generation ✂️ if this is true, only the text elements of a header get used for generating the ID later (in contrast to just using the raw header text line).
💀 heads up: 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 is true, ID values for all headers are automatically generated whenever no ID is explicitly specified.

Default: true — Used by: HTML/Latex 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
    • :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 characters will be escaped. and if that backlink text is an empty string, no footnote backlinks will be generated at all 🚫

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 gets placed at the end of the last paragraph if there is one, or else 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 that fails (e.g. in the case of a table), an extra paragraph with only the footnote backlink is created anyway.

Default: false — Used by: HTML converter

  • --footnote-link-text ARG — the text used for the footnote number in a footnote link 🔢 this one lets you add extra text to the footnote link. It should be a format string, and it's passed the footnote number as the only argument to that format string. e.g. [footnote %s] would display as [footnote 1] ✨

Default: ‘%s’ — Used by: HTML

  • --footnote-nr ARG — the number of the first footnote 🥇 lets you specify the number used for the first footnote.

Default: 1 — Used by: HTML converter

  • --footnote-prefix ARG — prefix used for footnote IDs 🏷️ super handy when you're rendering multiple documents into the same output file and you want to avoid duplicate IDs. and yeah — the prefix should only contain characters that are valid in an ID!

Default: ‘’ — Used by: HTML

  • --forbidden-inline-options ARG — defines the options that may not be set using the {::options} extension 🙅 the value needs to be an array of option names.

Default: [template] — Used by: HTML converter

  • --[no-]header-links — adds anchor tags within headers that can be used to generate permalinks when you're not using a table of contents 🔗 the anchor tags are empty, but you can style them to your liking 💅

Default: false

  • --header-offset ARG — sets the output offset for headers 📐 if this option is c (it 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. math, but make it slay 🧮

Default: 0 — Used by: HTML converter, Kramdown converter, Latex converter

  • --[no-]html-to-native — convert HTML elements to native elements 🔄 if this is true, the parser converts HTML elements to native elements. For example, when parsing <em>hallo</em> the emphasis tag would normally be converted to an :html element with tag type :em. But if html_to_native is true, then the emphasis would be converted to a native :em element instead. super useful for converters that can't deal with HTML elements 🙏

Default: false — Used by: kramdown parser

  • --latex-headers ARG — defines the LaTeX commands for different header levels 📜 the commands for header levels one through six can be specified by separating them with commas.

Default: section,subsection,subsubsection,paragraph,subparagraph,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 one lets you 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 that hash has to follow the guidelines above 👆

Default: {} — Used by: kramdown parser

  • --list-indent ARG — sets the number of spaces to use for list indentation ␣

Default: 2 — Used by: Kramdown converter

  • --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 engine 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 understood by the used math engine.

Default: {} — Used by: HTML converter

  • --[no-]parse-block-html — process kramdown syntax in block HTML tags 🧱 if this is true, the kramdown parser processes the content of block HTML tags as text containing block-level elements. Since this is not wanted normally, the default is false. It's 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 is true, the kramdown parser processes the content 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 is true, the RemoveHtmlTags converter removes block HTML tags.

Default: true — Used by: RemoveHtmlTags converter

  • --[no-]remove-line-breaks-for-cjk — specifies whether line breaks should be removed between CJK characters 🌏

Default: false — Used by: HTML converter

  • --[no-]remove-span-html-tags — remove span HTML tags 🗑️ if this 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 you wanna use for — in this exact order — a left single quote, a right single quote, a left double quote and a right double quote get picked by entity name or by code point, and you separate them with commas. That's the whole entire thing, no notes. 🎀

Default: lsquo,rsquo,ldquo,rdquo Used by: HTML/Latex converter

  • --syntax-highlighter ARG — picks the syntax highlighter, obviously 💅

This is the one that decides who's doing the glow-up on your code blocks and spans. Set it to +nil+ and no syntax highlighting happens at all — bare-faced, we're going natural, and honestly? valid.

Whatever options your chosen highlighter needs go in via the syntax_highlighter_opts configuration option.

Default: rouge Used by: HTML/Latex converter

  • --syntax-highlighter-opts ARG — hands your highlighter its little snack pack 🍓

These are the options for whatever highlighter you set with the syntax_highlighter configuration option.

The value has to be a hash with key-value pairs that the highlighter you're actually using understands. It doesn't magically know, bestie — it's gotta be a real hash it gets.

Default: {} Used by: HTML/Latex converter

  • --template ARG — wraps your output in a cute lil outfit 🎀

This is the name of an ERB template file that should wrap the output, or the ERB template itself, right there in the argument.

It's used to wrap your output in an environment so the result can stand on its own as a whole document. Say you've got an HTML template — it supplies the header and body tags so your whole output is a legit, valid HTML file. If you give it no template at all, you just get the converted text and nothing else.

Now here's how it finds the thing, in order, no skipping 💀:

  1. The template name you gave is tried first.
  2. If that file isn't found, the converter extension gets appended — that's the same extension as the converter name.
  3. If it still can't find it, the template name is treated as a template name that kramdown itself provides (without the converter extension).
  4. If the file is still not found, the template name gets checked for starting with ‘string://’ — and if it does, that prefix is removed and the rest is used as the template content.

kramdown ships with a default template named ‘document’ for every single converter, so you're never truly alone. 🫶

Default: ‘’ (yes, empty, the void, nothing) Used by: all converters

  • --toc-levels ARG — sets which heading levels make it into the table of contents 📋

You list the levels by separating them with commas (like 1,2,3) or you use the range syntax (like 1..3). Only the levels you list get used in the table of contents. That's it, that's the rule.

Default: 1..6 Used by: HTML/Latex converter

  • --[no-]transliterated-header-ids — transliterates the header text before generating the ID ✨

Only ASCII characters go into header IDs, which is kind of a problem for languages rocking a whole lotta non-ASCII characters. Turn this option on and the header text gets transliterated to ASCII as best as it possibly can be, so the resulting header ID is actually useful instead of cursed.

The stringex library has to be installed for this feature to work at all! No library, no transliteration, periodt.

Default: false Used by: HTML/Latex converter

  • --typographic-symbols ARG — maps typographical symbols to the characters that get output 🔤

Typographical symbols normally get output as their equivalent Unicode codepoint. But sometimes you want to change that up — usually to fall back to a sequence of ASCII characters instead.

This option is how you do it: you give a mapping from typographical symbol to its output string. For example, the mapping {hellip: ...} would output the standard ASCII representation of an ellipsis. Cute and functional.

The available typographical symbol names are:

  • hellip — ellipsis
  • mdash — em-dash
  • ndash — en-dash
  • laquo — left guillemet
  • raquo — right guillemet
  • laquo_space — left guillemet followed by a space
  • raquo_space — right guillemet preceded by a space

Default: {} Used by: HTML/Latex converter

🚦 EXIT STATUS

The exit status is 0 if no error happened. Otherwise it's 1. That's it. Clean success or a lil snack of failure, no in-between 🌈

👀 SEE ALSO

The kramdown website at http://kramdown.gettalong.org for more information — especially if you wanna know about the supported input syntax. Go read it, it slaps.

👑 AUTHOR

kramdown was written by Thomas Leitner t_leitner@gmx.at .

This manual page was written by Thomas Leitner t_leitner@gmx.at .

and that's the whole page, bestie!! 💖✨ This was KRAMDOWN(1) — dated January 2019 — so if you're reading this way later, hi, you're doing amazing, go render some markdown 💅🦋

📦 where this page comes from