Kramdown Specification

Check out the Markdown Dingus to experiment with the Kramdown processor.

What is Kramdown?

Kramdown is a fast, pure-Ruby Markdown-superset converter that extends the original Markdown syntax with features found in other implementations like Maruku, PHP Markdown Extra, and Pandoc. It provides a strict syntax with definite rules while maintaining compatibility with most Markdown documents.

Key Characteristics

  • Fast and Pure Ruby: Written entirely in Ruby for performance and portability
  • Strict Syntax: Provides definite rules and clear specifications
  • Enhanced Features: Includes many extensions not found in standard Markdown
  • Jekyll Integration: Default Markdown processor for Jekyll static site generator
  • Comprehensive: Supports both block-level and span-level elements with extensive customization

Major Differences from Standard Markdown

1. Enhanced Block-Level Elements

Definition Lists

  • Kramdown supports definition lists (not in standard Markdown)
  • Uses : to separate terms from definitions
Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b

Tables

  • Full table support with headers, alignment, and formatting
  • More comprehensive than basic Markdown table syntax
| Header 1 | Header 2 | Header 3 |
| :------- | :------: | -------: |
| Left     |  Center  |    Right |
| Aligned  | Aligned  |  Aligned |

Math Blocks

  • Support for mathematical expressions using LaTeX syntax
  • Both inline and block math support
Inline math: $E = mc^2$

Block math:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

2. Advanced Text Markup

Footnotes

  • Full footnote support with automatic numbering
  • Reference-style footnotes with [^1] syntax
This is a sentence with a footnote[^1].

[^1]: This is the footnote content.

Abbreviations

  • Support for HTML-style abbreviations
  • Automatic expansion of defined abbreviations
*[HTML]: HyperText Markup Language
*[CSS]: Cascading Style Sheets

This uses HTML and CSS.

Typographic Symbols

  • Automatic conversion of common typographic characters
  • Smart quotes, em dashes, ellipses, etc.
"Smart quotes" and -- em dashes -- and ... ellipses
Even << guillemets >>

3. Attribute Lists and Extensions

Attribute List Definitions (ALDs)

  • Define reusable attribute sets
  • Support for IDs, classes, and custom attributes
{:ref-name: #myid .my-class title="My Title"}

A paragraph with attributes.
{: #para-one .highlight}

Inline Attribute Lists (IALs)

  • Attach attributes to specific elements
  • Both block-level and span-level support
This *is*{:.underline} some `code`{:#id}{:.class}.
A [link](test.html){:rel='something'} and some **tools**{:.tools}.

Extensions

  • Custom extension system for additional functionality
  • Built-in extensions for comments and options
{::comment}
This text is completely ignored by kramdown.
{:/comment}

{::options key="val" /}

4. Enhanced Code Block Support

Language Specification

  • Automatic syntax highlighting for fenced code blocks

  • Support for many programming languages

    def hello
  puts "Hello, World!"
end

Standard Code Blocks

  • Improved handling of indented code blocks
  • Better integration with other block elements

5. Stricter Parsing Rules

Line Wrapping

  • Support for hard-wrapped content (lazy syntax)
  • Clear rules for when line wrapping is allowed
  • Not recommended for readability but supported for compatibility

Tab Handling

  • Assumes tab stops at multiples of four
  • Tabs only allowed at beginning of lines for indentation
  • Must not be preceded by spaces

Block Boundaries

  • Clear rules for when elements must start/end on block boundaries
  • Consistent behavior across different element types

6. Advanced Link and Image Support

Automatic Links

  • Enhanced automatic link detection
  • Better handling of URLs and email addresses

Reference Links

  • Improved reference link processing
  • Better conflict resolution for multiple definitions

Image Attributes

  • Support for image attributes through IALs
  • Width, height, alt text, and other HTML attributes
![Alt text](image.jpg){:width="300" height="200" class="responsive"}

7. HTML Integration

HTML Blocks

  • Better handling of HTML within Markdown
  • Support for HTML attributes and processing
  • More flexible than standard Markdown HTML handling

HTML Spans

  • Inline HTML with attribute support
  • Better integration with Markdown syntax

8. Mathematical Expressions

Inline Math

  • $...$ syntax for inline mathematical expressions
  • LaTeX-compatible syntax

Block Math

  • $$...$$ syntax for block mathematical expressions
  • Support for complex equations and formulas

Kramdown vs Other Markdown Flavors

Feature Kramdown CommonMark GitHub Flavored MultiMarkdown Standard
Strikethrough No Yes No No No
Task Lists No No Yes Yes No
Fenced Code Yes Yes Yes Yes No
Math Yes No Yes Yes No
Footnotes Yes Yes Yes Yes No
Definition Lists Yes No No Yes No
Abbreviations Yes No No No No
Attribute Lists Yes No No No No
Typography Yes No No Yes No

Key Advantages of Kramdown

  1. Comprehensive Feature Set: Includes many extensions not found in other implementations
  2. Jekyll Integration: Seamless integration with Jekyll static site generator
  3. Ruby Ecosystem: Pure Ruby implementation with good Ruby tooling support
  4. Extensibility: Custom extension system for additional functionality
  5. Attribute Support: Rich attribute system for HTML output customization
  6. Mathematical Support: Built-in support for LaTeX math expressions
  7. Strict Parsing: Clear, unambiguous parsing rules

Common Use Cases

Jekyll Sites

  • Default processor for Jekyll static site generation
  • Excellent for documentation and blog sites

Technical Documentation

  • Math support for scientific and technical writing
  • Attribute lists for advanced HTML customization

Academic Writing

  • Footnote support for citations and references
  • Mathematical expressions for formulas and equations

Content Management

  • Extensions for custom functionality
  • Attribute lists for metadata and styling

Resources

Migration from Standard Markdown

Most standard Markdown documents work with Kramdown without modification. To take advantage of Kramdown’s features:

  1. Add Definition Lists: Convert glossaries and term lists
  2. Use Attribute Lists: Add IDs, classes, and custom attributes
  3. Implement Footnotes: Convert parenthetical references

Best Practices

  1. Avoid Lazy Syntax: Don’t rely on hard-wrapping for readability
  2. Use Attribute Lists: Leverage IALs for styling and metadata
  3. Consistent Indentation: Use spaces instead of tabs when possible

This documentation covers Kramdown 2.5.1. For the most current information, always refer to the official documentation at kramdown.gettalong.org.

Next up: Discount GFM Specification ▶

Search | Support Site | Knowledgebase | Legal | Privacy | Twitter