kramdown

https://kramdown.gettalong.org/
Admin
kramdown is a fast, pure-Ruby Markdown-superset converter that supports multiple input formats...
Tokens:65,861
Snippets:762
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install kramdown manually

Source: https://kramdown.gettalong.org/installation.html

Use the setup.rb script to install kramdown after downloading the source package.

```bash
$ ruby setup.rb config
$ ruby setup.rb setup
$ ruby setup.rb install
```

--------------------------------

### Install Ruby on Ubuntu

Source: https://kramdown.gettalong.org/installation.html

Use the apt package manager to install the Ruby interpreter on Debian-based systems.

```bash
sudo apt-get install ruby
```

--------------------------------

### Initialize and convert a Kramdown document

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Document.html

Basic usage example showing how to instantiate a document and convert it to HTML.

```ruby
require 'kramdown'
doc = Kramdown::Document.new('This *is* some kramdown text')
puts doc.to_html
```

--------------------------------

### Install kramdown via Rubygems

Source: https://kramdown.gettalong.org/installation.html

Standard installation command for kramdown using the RubyGems package manager.

```bash
sudo gem install kramdown
```

```bash
gem install kramdown
```

--------------------------------

### HTML block parsing example

Source: https://kramdown.gettalong.org/syntax.html

Demonstrates input Markdown and the resulting HTML output when parse_block_html is false.

```markdown
This is a para.
<div>
Something in here.
</div>
Other para.
```

```html
<p>This is a para.</p>
<div>
Something in here.
</div>
<p>Other para.</p>
```

--------------------------------

### Create a simplified kramdown table

Source: https://kramdown.gettalong.org/syntax.html

This example shows a more concise syntax for the same table structure, omitting full-width separators.

```markdown
|---
| Default aligned | Left aligned | Center aligned | Right aligned
|-|:-|:-:|-:
| First body part | Second cell | Third cell | fourth cell
| Second line |foo | **strong** | baz
| Third line |quux | baz | bar
|---
| Second body
| 2 line
|===
| Footer row
```

--------------------------------

### List indentation and nesting examples

Source: https://kramdown.gettalong.org/syntax.html

Illustrates how varying indentation levels create nested lists or multi-line list items.

```markdown
* list 1 item 1
 * list 1 item 2 (indent 1 space)
  * list 1 item 3 (indent 2 spaces)
   * list 1 item 4  (indent 3 spaces)
    * lazy text belonging to above item 4

```

```markdown
1. list 1 item 1
 2. list 1 item 2 (indent 1 space)
  3. list 1 item 3 (indent 2 spaces)
   4. list 1 item 4  (indent 3 spaces)
    5. lazy text belonging to above item 4

```

```markdown
* list 1 item 1
  * nested list item 1
  * nested list item 2
* list 1 item 2
  * nested list item 1

```

```markdown
1. list 1 item 1
   1. nested list item 1
   2. nested list item 2
10. list 1 item 2
    1. nested list item 1

```

```markdown
1. text for this list item
   further text (indent 3 spaces)

10. text for this list item
    further text (indent 4 spaces)

```

--------------------------------

### Paragraph Syntax Example

Source: https://kramdown.gettalong.org/syntax.html

Demonstrates paragraph indentation, line wrapping, and explicit line breaks using trailing spaces or backslashes.

```text
This⋅para⋅line⋅starts⋅at⋅the⋅first⋅column.⋅However,
⋅⋅⋅⋅⋅⋅the⋅following⋅lines⋅can⋅be⋅indented⋅any⋅number⋅of⋅spaces/tabs.
⋅⋅⋅The⋅para⋅continues⋅here.

⋅⋅This⋅is⋅another⋅paragraph,⋅not⋅connected⋅to⋅the⋅above⋅one.⋅But⋅⋅
with⋅a⋅hard⋅line⋅break.⋅\
And⋅another⋅one.

```

--------------------------------

### Initialize StringScanner

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Utils/StringScanner.html

Initializes the scanner with an optional start line number.

```ruby
def initialize(string, start_line_number = 1)
  super(string)
  @start_line_number = start_line_number || 1
  @previous_pos = 0
  @previous_line_number = @start_line_number
end
```

--------------------------------

### Define Abbreviations

Source: https://kramdown.gettalong.org/syntax.html

Examples of defining abbreviations and applying attributes using block IALs.

```markdown
This is some text not written in HTML but in another language!

*[another language]: It's called Markdown

*[HTML]: HyperTextMarkupLanguage
{:.mega-big}
```

--------------------------------

### Handle HTML start tags

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Html/Parser.html

Processes an HTML start tag that has already been scanned. It yields to the caller for further processing of the element, closure status, and body handling.

```ruby
# File lib/kramdown/parser/html.rb, line 87
def handle_html_start_tag(line = nil) # :yields: el, closed, handle_body
  name = @src[1]
  name.downcase! if HTML_ELEMENT[name.downcase]
  closed = !@src[4].nil?
  attrs = parse_html_attributes(@src[2], line, HTML_ELEMENT[name])

  el = Element.new(:html_element, name, attrs, category: :block)
  el.options[:location] = line if line
  @tree.children << el

  if !closed && HTML_ELEMENTS_WITHOUT_BODY.include?(el.value)
    closed = true
  end
  if name == 'script' || name == 'style'
    handle_raw_html_tag(name)
    yield(el, false, false)
  else
    yield(el, closed, true)
  end
end
```

--------------------------------

### Create a complex kramdown table

Source: https://kramdown.gettalong.org/syntax.html

This example demonstrates a table with a header, two body sections, and a footer using full-width separator lines.

```markdown
|-----------------+------------+-----------------+----------------|
| Default aligned |Left aligned| Center aligned  | Right aligned  |
|-----------------|:-----------|:---------------:|---------------:|
| First body part |Second cell | Third cell      | fourth cell    |
| Second line     |foo         | **strong**      | baz            |
| Third line      |quux        | baz             | bar            |
|-----------------+------------+-----------------+----------------|
| Second body     |            |                 |                |
| 2 line          |            |                 |                |
|=================+============+=================+================|
| Footer row      |            |                 |                |
|-----------------+------------+-----------------+----------------|
```

--------------------------------

### atx Style Headers

Source: https://kramdown.gettalong.org/syntax.html

Examples of atx style headers using hash characters to define heading levels.

```markdown
# First level header

### Third level header    ###

## Second level header ######
```

--------------------------------

### Define kramdown extensions

Source: https://kramdown.gettalong.org/syntax.html

Examples of using comment and options extensions within a kramdown document.

```markdown
{::comment}
This text is completely ignored by kramdown - a comment in the text.
{:/comment}

Do you see {::comment}this text{:/comment}?
{::comment}some other comment{:/}

{::options key="val" /}
```

--------------------------------

### Start list item with a code block

Source: https://kramdown.gettalong.org/syntax.html

Uses specific indentation to allow a code block to be the first element of a list item.

```markdown
*⋅
⋅⋅⋅⋅⋅⋅⋅⋅This⋅is⋅a⋅code⋅block⋅(indentation⋅needs⋅to⋅be⋅4(1)+4(1)
⋅⋅⋅⋅⋅⋅⋅⋅spaces⋅(tabs)).
```

--------------------------------

### Parse Extension Start Tag

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Kramdown.html

Parses generic block or span extensions, handling attributes and stop tags.

```ruby
# File lib/kramdown/parser/kramdown/extensions.rb, line 53
def parse_extension_start_tag(type)
  saved_pos = @src.save_pos
  start_line_number = @src.current_line_number
  @src.pos += @src.matched_size

  error_block = lambda do |msg|
    warning(msg)
    @src.revert_pos(saved_pos)
    add_text(@src.getch) if type == :span
    false
  end

  if @src[4] || @src.matched == '{:/}'
    name = (@src[4] ? "for '#{@src[4]}' " : '')
    return error_block.call("Invalid extension stop tag #{name} found on line " \
                            "#{start_line_number} - ignoring it")
  end

  ext = @src[1]
  opts = {}
  body = nil
  parse_attribute_list(@src[2] || '', opts)

  unless @src[3]
    stop_re = (type == :block ? /#{EXT_BLOCK_STOP_STR % ext}/ : /#{EXT_STOP_STR % ext}/)
    if (result = @src.scan_until(stop_re))
      body = result.sub!(stop_re, '')
      body.chomp! if type == :block
    else
      return error_block.call("No stop tag for extension '#{ext}' found on line " \
                              "#{start_line_number} - ignoring it")
    end
  end

  if handle_extension(ext, opts, body, type, start_line_number)
    true
  else
    error_block.call("Invalid extension with name '#{ext}' specified on line " \
                     "#{start_line_number} - ignoring it")
  end
end
```

--------------------------------

### Applying Block Inline Attribute Lists

Source: https://kramdown.gettalong.org/syntax.html

Examples of attaching IDs, titles, and classes to block-level elements like paragraphs, blockquotes, and code blocks.

```text
A simple paragraph with an ID attribute.
{: #para-one}

> A blockquote with a title
{:title="The blockquote title"}
{: #myid}

{:.ruby}
    Some code here
```

--------------------------------

### Define Footnotes

Source: https://kramdown.gettalong.org/syntax.html

Examples of various footnote definitions, including blockquotes and code blocks.

```markdown
[^1]: Some *crazy* footnote definition.

[^footnote]:
    > Blockquotes can be in a footnote.

        as well as code blocks

    or, naturally, simple paragraphs.

[^other-note]:       no code block here (spaces are stripped away)

[^codeblock-note]:
        this is now a code block (8 spaces indentation)
```

--------------------------------

### Escape list markers

Source: https://kramdown.gettalong.org/syntax.html

Escapes list markers to prevent them from being interpreted as the start of a list.

```markdown
1984\. It was great
\- others say that, too!
```

--------------------------------

### Applying Span Inline Attribute Lists

Source: https://kramdown.gettalong.org/syntax.html

Examples of attaching attributes directly to span-level elements like emphasis, code, and links.

```text
This *is*{:.underline} some `code`{:#id}{:.class}.
A [link](test.html){:rel='something'} and some **tools**{:.tools}.
```

--------------------------------

### Setext Header and Horizontal Rule Ambiguity

Source: https://kramdown.gettalong.org/syntax.html

Example showing that Setext headers take precedence over horizontal rules.

```markdown
header
---
para
```

--------------------------------

### List of span-level HTML tags

Source: https://kramdown.gettalong.org/syntax.html

These tags do not trigger the start of an HTML block when found at the beginning of a line.

```text
a abbr acronym b big bdo br button cite code del dfn em i img input
ins kbd label option q rb rbc rp rt rtc ruby samp select small span
strong sub sup textarea tt var
```

--------------------------------

### Include tildes within a fenced code block

Source: https://kramdown.gettalong.org/syntax.html

Start the block with more tildes than the tildes contained within the code.

```markdown
~~~~~~~~~~~~
~~~~~~~
code with tildes
~~~~~~~~
~~~~~~~~~~~~~~~~~~
```

--------------------------------

### Lazy line wrapping in blockquotes

Source: https://kramdown.gettalong.org/syntax.html

Example of using lazy line wrapping for paragraphs within nested blockquotes.

```markdown
> This is a paragraph inside
a blockquote.
>
> > This is a nested paragraph
that continues here
> and here
> > and here

```

--------------------------------

### Create basic ordered and unordered lists

Source: https://kramdown.gettalong.org/syntax.html

Demonstrates the syntax for unordered lists using +, -, or * and ordered lists using numbers followed by a period.

```markdown
* kram
+ down
- now

1. kram
2. down
3. now

```

--------------------------------

### Define Command Options

Source: https://kramdown.gettalong.org/converter/man.html

Syntax for documenting command-line options using definition lists.

```markdown
`-o`, `--option`
: The description for the option.

`-k` *value*
`--key`=*value*
: Another description.

  The description can contain multiple block elements, even lists.
```

--------------------------------

### Initialize HTML Converter

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Html.html

Initializes the converter with a root document and options, setting up internal state for footnotes, table of contents, and syntax highlighting.

```ruby
def initialize(root, options)
  super
  @footnote_counter = @footnote_start = @options[:footnote_nr]
  @footnotes = []
  @footnotes_by_name = {}
  @footnote_location = nil
  @toc = []
  @toc_code = nil
  @indent = 2
  @stack = []

  # stash string representation of symbol to avoid allocations from multiple interpolations.
  @highlighter_class = " highlighter-#{options[:syntax_highlighter]}"
  @dispatcher = Hash.new {|h, k| h[k] = :"convert_#{k}" }
end
```

--------------------------------

### Get paragraph end

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Kramdown.html

Returns the paragraph end constant.

```ruby
# File lib/kramdown/parser/kramdown/paragraph.rb, line 55
def paragraph_end
  self.class::PARAGRAPH_END
end
```

--------------------------------

### Create nested ordered lists

Source: https://kramdown.gettalong.org/quickref.html

Demonstrates how to nest ordered lists using indentation.

```markdown
1. Item one
   1. sub item one
   2. sub item two
   3. sub item three
2. Item two
```

```html
<ol>
  <li>Item one
    <ol>
      <li>sub item one</li>
      <li>sub item two</li>
      <li>sub item three</li>
    </ol>
  </li>
  <li>Item two</li>
</ol>
```

--------------------------------

### Initialize the LaTeX converter

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Latex.html

Initializes the converter with the root element and options, setting up the packages set.

```ruby
def initialize(root, options)
  super
  @data[:packages] = Set.new
end
```

--------------------------------

### Retrieve Parser Data

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Kramdown.html

Get the Data structure associated with a specific parser name.

```ruby
# File lib/kramdown/parser/kramdown.rb, line 334
def self.parser(name = nil)
  @@parsers[name]
end
```

--------------------------------

### Get element category

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Element.html

Retrieves the category of an element, returning :block, :span, or nil.

```ruby
def self.category(el)
  CATEGORY[el.type] || el.options[:category]
end
```

--------------------------------

### Create definition lists with paragraphs

Source: https://kramdown.gettalong.org/quickref.html

Shows how to wrap definitions in paragraphs by adding a blank line before the definition.

```markdown
term

: definition
: definition
```

```html
<dl>
  <dt>term</dt>
  <dd>
    <p>definition</p>
  </dd>
  <dd>definition</dd>
</dl>
```

--------------------------------

### Get smart quote entity

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Base.html

Retrieves the entity representation for a smart quote element.

```ruby
# File lib/kramdown/converter/base.rb, line 247
def smart_quote_entity(el)
  res = @options[:smart_quotes][SMART_QUOTE_INDICES[el.value]]
  ::Kramdown::Utils::Entities.entity(res)
end
```

--------------------------------

### Create definition lists

Source: https://kramdown.gettalong.org/quickref.html

Shows how to associate terms with definitions using colons.

```markdown
term
: definition
: another definition

another term
and another term
: and a definition for the term
```

```html
<dl>
  <dt>term</dt>
  <dd>definition</dd>
  <dd>another definition</dd>
  <dt>another term</dt>
  <dt>and another term</dt>
  <dd>and a definition for the term</dd>
</dl>
```

--------------------------------

### Create a simple link

Source: https://kramdown.gettalong.org/quickref.html

Surround link text with square brackets and the URL with parentheses.

```markdown
A [link](http://kramdown.gettalong.org)
to the kramdown homepage.
```

```html
<p>A <a href="http://kramdown.gettalong.org">link</a>
to the kramdown homepage.</p>
```

--------------------------------

### Kramdown::Document.new

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Document.html

Initializes a new Kramdown document by parsing the provided source string with specified options.

```APIDOC
## Kramdown::Document.new(source, options = {})

### Description
Creates a new Kramdown document from the string `source` and uses the provided `options` to configure the parser and converter. The document is parsed immediately upon initialization.

### Parameters
- **source** (String) - Required - The input text to be parsed.
- **options** (Hash) - Optional - Configuration options for the parser and converter. The `:input` key can be used to specify the parser class name (e.g., 'kramdown').

### Usage Example
```ruby
require 'kramdown'
doc = Kramdown::Document.new('This *is* some kramdown text', {input: 'kramdown'})
```
```

--------------------------------

### Get current line number

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Utils/StringScanner.html

Calculates the current line number based on the scan position.

```ruby
def current_line_number
  # Not using string[@previous_pos..best_pos].count('\n') because it is slower
  strscan = ::StringScanner.new(string)
  strscan.pos = @previous_pos
  old_pos = pos + 1
  @previous_line_number += 1 while strscan.skip_until(/\n/) && strscan.pos <= old_pos

  @previous_pos = (eos? ? pos : pos + 1)
  @previous_line_number
end
```

--------------------------------

### Kramdown::Document#initialize implementation

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Document.html

The constructor parses the source string using the specified input parser and initializes the document options.

```ruby
# File lib/kramdown/document.rb, line 95
def initialize(source, options = {})
  @options = Options.merge(options).freeze
  parser = (@options[:input] || 'kramdown').to_s
  parser = parser[0..0].upcase + parser[1..-1]
  try_require('parser', parser)
  if Parser.const_defined?(parser)
    @root, @warnings = Parser.const_get(parser).parse(source, @options)
  else
    raise Kramdown::Error, "kramdown has no parser to handle the specified " \
      "input format: #{@options[:input]}"
  end
end
```

--------------------------------

### Define Man Page Title

Source: https://kramdown.gettalong.org/converter/man.html

Valid syntax for the required level one heading at the start of the document.

```markdown
# name(section) -- short description of functionality

# name -- short description of functionality

# name(section)

# name short description of functionality

# name
```

--------------------------------

### Prepare Rouge configuration

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/SyntaxHighlighter/Rouge.html

Initializes and caches the syntax highlighter options, separating span and block configurations.

```ruby
# File lib/kramdown/converter/syntax_highlighter/rouge.rb, line 41
def self.prepare_options(converter)
  return if converter.data.key?(:syntax_highlighter_rouge)

  cache = converter.data[:syntax_highlighter_rouge] = {}

  opts = converter.options[:syntax_highlighter_opts].dup

  span_opts = opts.delete(:span)&.dup || {}
  block_opts = opts.delete(:block)&.dup || {}
  normalize_keys(span_opts)
  normalize_keys(block_opts)

  cache[:span] = opts.merge(span_opts)
  cache[:span][:wrap] = false

  cache[:block] = opts.merge(block_opts)
end
```

--------------------------------

### Create unordered lists

Source: https://kramdown.gettalong.org/quickref.html

Demonstrates mixing asterisk, dash, and plus signs for unordered list items.

```markdown
* Item one
+ Item two
- Item three
```

```html
<ul>
  <li>Item one</li>
  <li>Item two</li>
  <li>Item three</li>
</ul>
```

--------------------------------

### Configure parser

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Kramdown.html

Initializes the parser by setting up block and span parsers based on class configuration.

```ruby
# File lib/kramdown/parser/kramdown.rb, line 120
def configure_parser
  @parsers = {}
  (@block_parsers + @span_parsers).each do |name|
    if self.class.has_parser?(name)
      @parsers[name] = self.class.parser(name)
    else
      raise Kramdown::Error, "Unknown parser: #{name}"
    end
  end
  @span_start, @span_start_re = span_parser_regexps
end
```

--------------------------------

### Create a shortcut reference link

Source: https://kramdown.gettalong.org/quickref.html

Omit the second set of brackets if the link text is the same as the reference name.

```markdown
A link to the [kramdown hp].

[kramdown hp]: http://kramdown.gettalong.org "hp"
```

```html
<p>A link to the <a href="http://kramdown.gettalong.org" title="hp">kramdown hp</a>.</p>
```

--------------------------------

### Header Syntax

Source: https://kramdown.gettalong.org/quickref.html

Demonstrates standard Markdown header levels from H1 to H6.

```markdown
# H1 header

## H2 header

### H3 header

#### H4 header

##### H5 header

###### H6 header

```

```html
<h1>H1 header</h1>

<h2>H2 header</h2>

<h3>H3 header</h3>

<h4>H4 header</h4>

<h5>H5 header</h5>

<h6>H6 header</h6>

```

--------------------------------

### Create a reference-style link

Source: https://kramdown.gettalong.org/quickref.html

Define a reference name and URL separately to keep the text flow clean.

```markdown
A [link][kramdown hp]
to the homepage.

[kramdown hp]: http://kramdown.gettalong.org "hp"
```

```html
<p>A <a href="http://kramdown.gettalong.org" title="hp">link</a>
to the homepage.</p>
```

--------------------------------

### Use a Custom Parser

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Kramdown.html

Initialize a Kramdown::Document with the custom parser class specified in the options.

```ruby
require 'kramdown/document'
# require the file with the above parser class

Kramdown::Document.new(input_text, :input => 'ERBKramdown').to_html
```

--------------------------------

### Format as indented block HTML

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Html.html

Formats an element as block HTML with a newline after the start tag and indentation before the end tag.

```ruby
# File lib/kramdown/converter/html.rb, line 410
def format_as_indented_block_html(name, attr, body, indent)
  "#{' ' * indent}<#{name}#{html_attributes(attr)}>\n#{body}#{' ' * indent}</#{name}>\n"
end
```

--------------------------------

### LaTeX Environment and Link Handling

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Latex.html

Methods for wrapping content in LaTeX environments and generating hypertargets.

```ruby
def latex_environment(type, el, text)
  attrs = attribute_list(el)
  "\\begin{#{type}}#{latex_link_target(el)}#{attrs}\n#{text.rstrip}\n\\end{#{type}}#{attrs}\n"
end
```

```ruby
def latex_link_target(el, add_label = false)
  if (id = el.attr['id'])
    "\\hypertarget{#{id}}{}#{add_label ? "\\label{#{id}}" : ''}"
  else
    nil
  end
end
```

--------------------------------

### Kramdown::Converter::Toc.new(root, options)

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Toc.html

Initializes a new instance of the Toc converter.

```APIDOC
## new(root, options)

### Description
Initializes the Toc converter with the document root and configuration options.

### Parameters
- **root** (Object) - The root element of the Kramdown document.
- **options** (Hash) - Configuration options for the converter.
```

--------------------------------

### Setext Style Headers

Source: https://kramdown.gettalong.org/quickref.html

Shows the syntax for creating first and second level headers using Setext style underlining.

```markdown
First level header
==================

Second level header
-------------------

```

```html
<h1>First level header</h1>

<h2>Second level header</h2>


```

--------------------------------

### Initialize the TOC converter

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Toc.html

Initializes a new instance of the TOC converter with the document root and options.

```ruby
# File lib/kramdown/converter/toc.rb, line 26
def initialize(root, options)
  super
  @toc = Element.new(:toc)
  @stack = []
  @options[:template] = ''
end
```

--------------------------------

### HTML tags with whitespace-only text removal

Source: https://kramdown.gettalong.org/parser/html.html

List of HTML tags where whitespace-only text elements are removed if they appear at the start, end, or between block-level children.

```text
body section nav article aside header footer address
div li dd blockquote figure figcaption td th fieldset form
```

--------------------------------

### Create a simple definition list

Source: https://kramdown.gettalong.org/syntax.html

Basic usage of terms followed by a colon and definition text.

```kramdown
kramdown
: A Markdown-superset converter

Maruku
:     Another Markdown-superset converter

```

--------------------------------

### Retrieve all option definitions

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Options.html

Returns the internal collection of all option definitions.

```ruby
# File lib/kramdown/options.rb, line 61
def self.definitions
  @options
end
```

--------------------------------

### Using kramdown comment and nomarkdown extensions

Source: https://kramdown.gettalong.org/quickref.html

Demonstrates how to use the comment extension to ignore text and the nomarkdown extension to insert text as-is.

```markdown
This is a paragraph
{::comment}
This is a comment which is
completely ignored.
{:/comment}
... paragraph continues here.

Extensions can also be used
inline {::nomarkdown}**see**{:/}!
```

```html
<p>This is a paragraph
<!-- 
This is a comment which is
completely ignored.
 -->
… paragraph continues here.</p>

<p>Extensions can also be used
inline **see**!</p>
```

--------------------------------

### Configure kramdown via Command Line

Source: https://kramdown.gettalong.org/options.html

Use command line switches to set options, replacing underscores with dashes.

```bash
$ kramdown --no-auto-ids --footnote-nr 5
```

--------------------------------

### Access element options

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Element.html

Returns the options hash for the element, initializing it if necessary.

```ruby
def options
  @options ||= {}
end
```

--------------------------------

### Ordered List Syntax

Source: https://kramdown.gettalong.org/quickref.html

Create ordered lists using numbers followed by a period and a space.

```markdown
1. This is a list item
2. And another item
2. And the third one
   with additional text

```

```html
<ol>
  <li>This is a list item</li>
  <li>And another item</li>
  <li>And the third one
with additional text</li>
</ol>

```

--------------------------------

### Recommended list formatting

Source: https://kramdown.gettalong.org/syntax.html

Provides the preferred way to write lists with consistent indentation for better readability.

```markdown
* This is the first list item bla blabla blabla blabla blabla blabla
  blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla
  blabla blabla blabla bla
* This is the another item of the list. bla blabla blabla blabla blabla
  blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla

```

--------------------------------

### Initialize new element

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Element.html

Constructor for creating a new Element object with optional value, attributes, and options.

```ruby
def initialize(type, value = nil, attr = nil, options = nil)
  @type, @value, @attr, @options = type, value, attr, options
  @children = []
end
```

--------------------------------

### Parse source string into element tree

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Base.html

Initializes a new parser instance and executes the parsing process, returning the root element and any generated warnings.

```ruby
# File lib/kramdown/parser/base.rb, line 72
def self.parse(source, options = {})
  parser = new(source, options)
  parser.parse
  [parser.root, parser.warnings]
end
```

--------------------------------

### Convert files via command line

Source: https://kramdown.gettalong.org/documentation.html

Use the kramdown binary to convert files directly from the terminal.

```bash
kramdown path/to/kramdown/doc/syntax.page
```

--------------------------------

### Kramdown::Utils::LRUCache.new

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Utils/LRUCache.html

Initializes a new instance of the LRUCache with a specified maximum size.

```APIDOC
## Kramdown::Utils::LRUCache.new(size)

### Description
Creates a new LRUCache instance that can hold a maximum number of entries defined by the size parameter.

### Parameters
- **size** (Integer) - Required - The maximum number of entries the cache can store.
```

--------------------------------

### Apply block IAL to link definition

Source: https://kramdown.gettalong.org/news.html

Demonstrates applying attributes to a link definition using block IAL syntax.

```markdown
This is a ![resized image].

[resized image]: some_image.jpg "with a title"
{: height="36px" width="36px" style="border: 1px solid green"}
```

--------------------------------

### Create a table with alignment and footer

Source: https://kramdown.gettalong.org/quickref.html

Use pipe characters combined with dashes for separators and equal signs for footers to define complex table layouts.

```markdown
| Header1 | Header2 | Header3 |
|:--------|:-------:|--------:|
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
|----
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
|=====
| Foot1   | Foot2   | Foot3
{: rules="groups"}
```

--------------------------------

### Configure kramdown via Document Extension

Source: https://kramdown.gettalong.org/options.html

Set options directly within a kramdown document using the special extension syntax.

```text
{::options auto_ids="false" footnote_nr="5" syntax_highlighter_opts="{line_numbers: true}" /}
```

--------------------------------

### Kramdown::Options.define

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Options.html

Defines a new configuration option with a specified type, default value, and description. An optional block can be provided for custom validation.

```APIDOC
## Kramdown::Options.define(name, type, default, desc, &block)

### Description
Defines a new option called `name` (a Symbol) with the given `type` (String, Integer, Float, Symbol, Boolean, Object), default value `default` and the description `desc`. If a block is specified, it should validate the value and either raise an error or return a valid value.
```

--------------------------------

### Paragraphs and Line Breaks

Source: https://kramdown.gettalong.org/quickref.html

Demonstrates how consecutive lines form paragraphs and how to force line breaks using trailing spaces or backslashes.

```markdown
The first paragraph.

Another paragraph

```

```html
<p>The first paragraph.</p>

<p>Another paragraph</p>


```

```markdown
This is a paragraph  
which contains a hard line break.

```

```html
<p>This is a paragraph<br />
which contains a hard line break.</p>


```

--------------------------------

### Retrieve Rouge options

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/SyntaxHighlighter/Rouge.html

Fetches the prepared syntax highlighter options for a specific converter and type.

```ruby
# File lib/kramdown/converter/syntax_highlighter/rouge.rb, line 36
def self.options(converter, type)
  prepare_options(converter)
  converter.data[:syntax_highlighter_rouge][type]
end
```

--------------------------------

### Convert definition lists

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Latex.html

Converts definition lists (dl) to a description environment.

```ruby
def convert_dl(el, opts)
  latex_environment('description', el, inner(el, opts))
end
```

--------------------------------

### Create compact nested lists

Source: https://kramdown.gettalong.org/syntax.html

Demonstrates how kramdown supports compact nested lists without paragraph wrapping.

```markdown
*   This is just text.
    * this is a sub list item
      * this is a sub sub list item
* This is just text,
    spanning two lines
  * this is a nested list item.
```

--------------------------------

### Configure kramdown options

Source: https://kramdown.gettalong.org/documentation.html

Pass an options hash to the constructor to customize parsing behavior, such as disabling automatic header IDs.

```ruby
puts Kramdown::Document.new(text, :auto_ids => false).to_html
```

--------------------------------

### Initialize LRUCache

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Utils/LRUCache.html

Creates a new instance of LRUCache with a specified maximum size.

```ruby
# File lib/kramdown/utils/lru_cache.rb, line 20
def initialize(size)
  @size = size
  @cache = {}
end
```

--------------------------------

### Create a simple table

Source: https://kramdown.gettalong.org/quickref.html

Define a basic table structure using pipe characters to separate cells.

```markdown
| A simple | table |
| with multiple | lines|
```

--------------------------------

### Kramdown::Converter::SyntaxHighlighter::Minted.call

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/SyntaxHighlighter/Minted.html

Converts code text into LaTeX Minted format for syntax highlighting.

```APIDOC
## Kramdown::Converter::SyntaxHighlighter::Minted.call

### Description
Converts the provided code text into a LaTeX Minted environment or inline command based on the specified language and type.

### Parameters
- **converter** (Object) - The converter instance providing configuration options.
- **text** (String) - The source code text to be highlighted.
- **lang** (String) - The programming language of the code.
- **type** (Symbol) - The type of highlighting, either :block or :span.
- **_opts** (Hash) - Additional options.

### Returns
- **String** - The formatted LaTeX string for Minted, or nil if the language is not provided.
```

--------------------------------

### Kramdown::Parser::Base#adapt_source

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Base.html

Prepares a source string for parsing by normalizing line endings and encoding.

```APIDOC
## Kramdown::Parser::Base#adapt_source(source)

### Description
Modifies the input source string to ensure compatibility with the parser. It enforces UTF-8 encoding, unifies line endings to '\n', and ensures the string ends with a newline character.

### Parameters
- **source** (String) - Required - The raw source string to adapt.
```

--------------------------------

### Insert Images

Source: https://kramdown.gettalong.org/syntax.html

Syntax for inline and reference-style images with optional alternative text and titles.

```markdown
Here comes a ![smiley](../images/smiley.png)! And here
![too](../images/other.png 'Title text'). Or ![here].
With empty alt text ![](see.jpg)
```

--------------------------------

### Handle extensions

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Kramdown.html

Processes custom extensions like comments, raw blocks, or configuration options.

```ruby
# File lib/kramdown/parser/kramdown/extensions.rb, line 95
def handle_extension(name, opts, body, type, line_no = nil)
  case name
  when 'comment'
    if body.kind_of?(String)
      @tree.children << Element.new(:comment, body, nil, category: type, location: line_no)
    end
    true
  when 'nomarkdown'
    if body.kind_of?(String)
      @tree.children << Element.new(:raw, body, nil, category: type,
                                    location: line_no, type: opts['type'].to_s.split(/\s+/))
    end
    true
  when 'options'
    opts.select do |k, v|
      k = k.to_sym
      if Kramdown::Options.defined?(k)
        if @options[:forbidden_inline_options].include?(k) ||
            k == :forbidden_inline_options
          warning("Option #{k} may not be set inline")
          next false
        end

        begin
          val = Kramdown::Options.parse(k, v)
          @options[k] = val
          (@root.options[:options] ||= {})[k] = val
        rescue StandardError
        end
        false
      else
        true
      end
    end.each do |k, _v|
      warning("Unknown kramdown option '#{k}'")
    end
    @tree.children << new_block_el(:eob, :extension) if type == :block
    true
  else
    false
  end
end
```

--------------------------------

### Check template application timing

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Base.html

Methods to determine if a template should be applied before or after tree conversion.

```ruby
# File lib/kramdown/converter/base.rb, line 72
def apply_template_after?
  true
end
```

```ruby
# File lib/kramdown/converter/base.rb, line 65
def apply_template_before?
  false
end
```

--------------------------------

### Nested HTML blocks

Source: https://kramdown.gettalong.org/syntax.html

Demonstrates nesting multiple HTML div tags.

```html
<div id="content"><div id="layers"><div id="layer1">
This is some text in the `layer1` div.
</div>
This is some text in the `layers` div.
</div></div>
This is a para outside the HTML block.
```

--------------------------------

### Kramdown::Document#try_require implementation

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Document.html

Attempts to load a parser or converter file without raising an error if the file is missing.

```ruby
# File lib/kramdown/document.rb, line 128
def try_require(type, name)
  require("kramdown/#{type}/#{Utils.snake_case(name)}")
  true
rescue LoadError
  true
end
```

--------------------------------

### Define a configurable extension

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Utils/Configurable.html

Registers a new configurable extension by name, creating accessor methods for managing the extension's data.

```ruby
# File lib/kramdown/utils/configurable.rb, line 27
def configurable(name)
  unless respond_to?(:configurables)
    singleton_class.send(:define_method, :configurables) do
      @_configurables ||= Hash.new {|h, k| h[k] = {} }
    end
  end
  singleton_class.send(:define_method, name) do |data|
    configurables[name][data]
  end
  singleton_class.send(:define_method, "add_#{name}".intern) do |data, *args, &block|
    configurables[name][data] = args.first || block
  end
end
```

--------------------------------

### Convert document tree using Base class

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Base.html

The class method used to initialize a converter instance and process the document tree, including optional template application and encoding handling.

```ruby
# File lib/kramdown/converter/base.rb, line 100
def self.convert(tree, options = {})
  converter = new(tree, ::Kramdown::Options.merge(options.merge(tree.options[:options] || {})))

  if !converter.options[:template].empty? && converter.apply_template_before?
    apply_template(converter, '')
  end
  result = converter.convert(tree)
  if result.respond_to?(:encode!) && result.encoding != Encoding::BINARY
    result.encode!(tree.options[:encoding] ||
                   (raise ::Kramdown::Error, "Missing encoding option on root element"))
  end
  if !converter.options[:template].empty? && converter.apply_template_after?
    result = apply_template(converter, result)
  end

  [result, converter.warnings]
end
```

--------------------------------

### Handle list item indentation

Source: https://kramdown.gettalong.org/syntax.html

Shows how indentation affects list item content and how to avoid ambiguous lazy indentation.

```markdown
* This is the first line. Since the first non-space characters appears in
  column 3, all other indented lines have to be indented 2 spaces.
However, one could be lazy and not indent a line but this is not
recommended.
*       This is the another item of the list. It uses a different number
   of spaces for indentation which is okay but should generally be avoided.
   * The list item marker is indented 3 spaces which is allowed but should
     also be avoided and starts the third list item. Note that the lazy
     line in the second list item may make you believe that this is a
     sub-list which it isn't! So avoid being lazy!

```

--------------------------------

### Add header

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Kramdown.html

Creates and adds a header element to the document tree.

```ruby
# File lib/kramdown/parser/kramdown/header.rb, line 58
def add_header(level, text, id)
  start_line_number = @src.current_line_number
  @src.pos += @src.matched_size
  el = new_block_el(:header, nil, nil, level: level, raw_text: text, location: start_line_number)
  add_text(text, el)
  el.attr['id'] = id if id
  @tree.children << el
end
```

--------------------------------

### Inline links

Source: https://kramdown.gettalong.org/syntax.html

Creates links with text and optional titles using square brackets and parentheses.

```markdown
This is [a link](http://rubyforge.org) to a page.
A [link](../test "local URI") can also have a title.
And [spaces](link with spaces.html)!
```

--------------------------------

### Save parsing environment

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Parser/Kramdown.html

Returns the current parsing environment state.

```ruby
def save_env
  [@src, @tree, @block_ial, @stack, @text_type]
end
```

--------------------------------

### Apply ID using IAL shortcut

Source: https://kramdown.gettalong.org/quickref.html

Uses the hash prefix shortcut to assign an ID to a block element.

```markdown
> A nice blockquote
{: #with-an-id}
```

```html
<blockquote id="with-an-id">
  <p>A nice blockquote</p>
</blockquote>
```

--------------------------------

### Specify language using IAL

Source: https://kramdown.gettalong.org/syntax.html

Apply a language class using an Inline Attribute List (IAL) to enable syntax highlighting.

```ruby
~~~
def what?
  42
end
~~~
{: .language-ruby}
```

--------------------------------

### Convert Definition List

Source: https://kramdown.gettalong.org/rdoc/Kramdown/Converter/Html.html

Converts a definition list element to HTML.

```ruby
# File lib/kramdown/converter/html.rb, line 184
def convert_dl(el, indent)
  format_as_indented_block_html("dl", el.attr, inner(el, indent), indent)
end
```

--------------------------------

### Equivalent Class Name Attribute Definitions

Source: https://kramdown.gettalong.org/syntax.html

Demonstrates how class names are appended to the class attribute and how later definitions overwrite earlier ones.

```text
{:id: .cls1 .cls2}
{:id: class="cls1" .cls2}
{:id: class="something" class="cls1" .cls2}
{:id: class="cls1 cls2"}
```

--------------------------------

### Create a link with a title

Source: https://kramdown.gettalong.org/quickref.html

Add a title attribute to a link by including it in quotes within the parentheses.

```markdown
A [link](http://kramdown.gettalong.org "hp")
to the homepage.
```

```html
<p>A <a href="http://kramdown.gettalong.org" title="hp">link</a>
to the homepage.</p>
```
Tokens:
Raw