Represents all elements in the element tree.
kramdown only uses this one class for representing all available elements in an element tree (paragraphs, headers, emphasis, …). The type of element can be set via the type accessor.
Following is a description of all supported element types.
Note that the option :location may contain the start line number of an element in the source document.
None
As the root element of a document
Block-level elements
Represents the root of a kramdown document.
The root element contains the following option keys:
When running on Ruby 1.9 this key has to be set to the encoding used for the text parts of the kramdown document.
This key may be used to store the mapping of abbreviation to abbreviation definition.
This key may be used to store the mapping of abbreviation to abbreviation attributes.
This key may be used to store options that were set during parsing of the document.
Block-level element
Where block-level elements are expected
Empty
Represents one or more blank lines. It is not allowed to have two or more consecutive blank elements.
The value
field may contain the original content of the blank
lines.
Block-level element
Where block-level elements are expected
Span-level elements
Represents a paragraph.
If the option :transparent is true
, this element just
represents a block of text. I.e. this element just functions as a container
for span-level elements.
Block-level element
Where block-level elements are expected
Span-level elements
Represents a header.
The option :level specifies the header level and has to contain a number between 1 and 6. The option :raw_text has to contain the raw header text.
Block-level element
Where block-level elements are expected
Block-level elements
Represents a blockquote.
Block-level element
Where block-level elements are expected
Empty
Represents a code block, i.e. a block of text that should be used as-is.
The value
field has to contain the content of the code block.
Block-level element
Where block-level elements are expected
One or more :li elements
Represents an unordered list.
Block-level element
Where block-level elements are expected
One or more :li elements
Represents an ordered list.
Block-level element
Inside :ol and :ul elements
Block-level elements
Represents a list item of an ordered or unordered list.
Note that the first child of a list item must not be a :blank element!
Block-level element
Where block-level elements are expected
One or more groups each consisting of one or more :dt elements followed by one or more :dd elements.
Represents a definition list which contains groups consisting of terms and definitions for them.
Block-level element
Before :dt or :dd elements inside a :dl elment
Span-level elements
Represents the term part of a term-definition group in a definition list.
Block-level element
After :dt or :dd elements inside a :dl elment
Block-level elements
Represents the definition part of a term-definition group in a definition list.
Block-level element
Where block-level elements are expected
None
Represents a horizontal line.
Block-level element
Where block-level elements are expected
Zero or one :thead elements, one or more :tbody elements, zero or one :tfoot elements
Represents a table. Each table row (i.e. :tr element) of the table has to contain the same number of :td elements.
The option :alignment has to be an array containing the alignment values, exactly one for each column of the table. The possible alignment values are :left, :center, :right and :default.
None
As first element inside a :table element
One or more :tr elements
Represents the table header.
None
After a :thead element but before a :tfoot element inside a :table element
One or more :tr elements
Represents a table body.
None
As last element inside a :table element
One or more :tr elements
Represents the table footer.
None
Inside :thead, :tbody and :tfoot elements
One or more :td elements
Represents a table row.
Block-level element
Inside :tr elements
As child of :thead/:tr span-level elements, as child of :tbody/:tr and :tfoot/:tr block-level elements
Represents a table cell.
Block/span-level element
Where block/span-level elements are expected
None
Represents mathematical text that is written in LaTeX.
The value
field has to contain the actual mathematical text.
The option :category has to be set to either :span or :block depending on the context where the element is used.
Span-level element
Where span-level elements are expected
None
Represents text.
The value
field has to contain the text itself.
Span-level element
Where span-level elements are expected
None
Represents a hard line break.
Span-level element
Where span-level elements are expected
Span-level elements
Represents a link to an URL.
The attribute href
has to be set to the URL to which the link
points. The attribute title
optionally contains the title of
the link.
Span-level element
Where span-level elements are expected
None
Represents an image.
The attribute src
has to be set to the URL of the image. The
attribute alt
has to contain a text description of the image.
The attribute title
optionally contains the title of the
image.
Span-level element
Where span-level elements are expected
None
Represents verbatim text.
The value
field has to contain the content of the code span.
Span-level element
Where span-level elements are expected
None
Represents a footnote marker.
The value
field has to contain an element whose children are
the content of the footnote. The option :name has to contain a valid and
unique footnote name. A valid footnote name consists of a word character or
a digit and then optionally followed by other word characters, digits or
dashes.
Span-level element
Where span-level elements are expected
Span-level elements
Represents emphasis of its contents.
Span-level element
Where span-level elements are expected
Span-level elements
Represents strong importance for its contents.
Span-level element
Where span-level elements are expected
None
Represents an HTML entity.
The value
field has to contain an instance of Kramdown::Utils::Entities::Entity.
The option :original can be used to store the original representation of
the entity.
Span-level element
Where span-level elements are expected
None
Represents a typographic symbol.
The value
field needs to contain a Symbol representing the
specific typographic symbol from the following list:
An mdash character (—)
An ndash character (–)
An ellipsis (…)
A left guillemet (<<)
A right guillemet (>>)
A left guillemet with a space (<< )
A right guillemet with a space ( >>)
Span-level element
Where span-level elements are expected
None
Represents a quotation character.
The value
field needs to contain a Symbol representing the
specific quotation character:
Left single quote
Right single quote
Left double quote
Right double quote
Span-level element
Where span-level elements are expected
None
Represents a text part that is an abbreviation.
The value
field has to contain the text part that is the
abbreviation. The definition of the abbreviation is stored in the :root
element of the document.
Block/span-level element
Where block/span-level elements or raw HTML elements are expected
Depends on the element
Represents an HTML element.
The value
field has to contain the name of the HTML element
the element is representing.
The option :category has to be set to either :span or :block depending on the whether the element is a block-level or a span-level element. The option :content_model has to be set to the content model for the element (either :block if it contains block-level elements, :span if it contains span-level elements or :raw if it contains raw content).
Block/span-level element
Where block/span-level elements are expected or in raw HTML elements
None
Represents an XML/HTML comment.
The value
field has to contain the whole XML/HTML comment
including the delimiters.
The option :category has to be set to either :span or :block depending on the context where the element is used.
Block/span-level element
Where block/span-level elements are expected or in raw HTML elements
None
Represents an XML/HTML processing instruction.
The value
field has to contain the whole XML/HTML processing
instruction including the delimiters.
The option :category has to be set to either :span or :block depending on the context where the element is used.
Block/span-level element
Where block/span-level elements are expected
None
Represents a comment.
The value
field has to contain the comment.
The option :category has to be set to either :span or :block depending on the context where the element is used. If it is set to :span, then no blank lines are allowed in the comment.
Block/span-level element
Where block/span-level elements are expected
None
Represents a raw string that should not be modified. For example, the element could contain some HTML code that should be output as-is without modification and escaping.
The value
field has to contain the actual raw text.
The option :category has to be set to either :span or :block depending on the context where the element is used. If it is set to :span, then no blank lines are allowed in the raw text.
The option :type can be set to an array of strings to define for which converters the raw string is valid.
The child elements of this element.
A symbol representing the element type. For example, :p or :blockquote.
The value of the element. The interpretation of this field depends on the type of the element. Many elements don't use this field.
Return the category of el
which can be :block, :span or
nil
.
Most elements have a fixed category, however, some elements can either appear in a block-level or a span-level context. These elements need to have the option :category correctly set.
# File lib/kramdown/element.rb, line 511 def self.category(el) CATEGORY[el.type] || el.options[:category] end
Create a new Element object of type
type
. The optional parameters value
,
attr
and options
can also be set in this
constructor for convenience.
# File lib/kramdown/element.rb, line 483 def initialize(type, value = nil, attr = nil, options = nil) @type, @value, @attr, @options = type, value, (Utils::OrderedHash.new.merge!(attr) if attr), options @children = [] end
The attributes of the element. Uses an Utils::OrderedHash to retain the insertion order.
# File lib/kramdown/element.rb, line 489 def attr @attr ||= Utils::OrderedHash.new end
The options hash for the element. It is used for storing arbitray options.
# File lib/kramdown/element.rb, line 494 def options @options ||= {} end