kramdown 0.10.0 → 0.11.0
Sign up to get free protection for your applications and to get access to all the features.
Potentially problematic release.
This version of kramdown might be problematic. Click here for more details.
- data/CONTRIBUTERS +1 -1
- data/ChangeLog +594 -0
- data/Rakefile +2 -2
- data/VERSION +1 -1
- data/data/kramdown/document.html +11 -2
- data/doc/default.template +2 -2
- data/doc/index.page +1 -2
- data/doc/quickref.page +2 -2
- data/doc/syntax.page +270 -179
- data/lib/kramdown/converter/html.rb +43 -29
- data/lib/kramdown/converter/kramdown.rb +97 -73
- data/lib/kramdown/converter/latex.rb +18 -13
- data/lib/kramdown/document.rb +8 -6
- data/lib/kramdown/options.rb +7 -10
- data/lib/kramdown/parser/html.rb +29 -21
- data/lib/kramdown/parser/kramdown.rb +19 -3
- data/lib/kramdown/parser/kramdown/abbreviation.rb +1 -0
- data/lib/kramdown/parser/kramdown/attribute_list.rb +18 -12
- data/lib/kramdown/parser/kramdown/autolink.rb +1 -1
- data/lib/kramdown/parser/kramdown/block_boundary.rb +46 -0
- data/lib/kramdown/parser/kramdown/blockquote.rb +7 -3
- data/lib/kramdown/parser/kramdown/codeblock.rb +5 -3
- data/lib/kramdown/parser/kramdown/escaped_chars.rb +1 -1
- data/lib/kramdown/parser/kramdown/extension.rb +22 -8
- data/lib/kramdown/parser/kramdown/footnote.rb +3 -2
- data/lib/kramdown/parser/kramdown/header.rb +10 -10
- data/lib/kramdown/parser/kramdown/html.rb +16 -14
- data/lib/kramdown/parser/kramdown/html_entity.rb +1 -1
- data/lib/kramdown/parser/kramdown/link.rb +8 -8
- data/lib/kramdown/parser/kramdown/list.rb +36 -29
- data/lib/kramdown/parser/kramdown/math.rb +15 -4
- data/lib/kramdown/parser/kramdown/paragraph.rb +14 -3
- data/lib/kramdown/parser/kramdown/table.rb +17 -9
- data/lib/kramdown/utils.rb +1 -0
- data/lib/kramdown/utils/html.rb +9 -9
- data/lib/kramdown/utils/ordered_hash.rb +79 -0
- data/lib/kramdown/version.rb +1 -1
- data/man/man1/kramdown.1 +9 -12
- data/test/test_files.rb +6 -1
- data/test/testcases/block/02_eob/middle.html +0 -1
- data/test/testcases/block/04_header/atx_header.html +5 -2
- data/test/testcases/block/04_header/atx_header.text +3 -1
- data/test/testcases/block/04_header/setext_header.html +4 -5
- data/test/testcases/block/04_header/setext_header.html.19 +30 -0
- data/test/testcases/block/05_blockquote/lazy.html +34 -0
- data/test/testcases/block/05_blockquote/lazy.text +20 -0
- data/test/testcases/block/05_blockquote/nested.html +1 -0
- data/test/testcases/block/05_blockquote/nested.text +1 -0
- data/test/testcases/block/05_blockquote/with_code_blocks.html +2 -2
- data/test/testcases/block/06_codeblock/lazy.html +4 -0
- data/test/testcases/block/06_codeblock/lazy.text +5 -0
- data/test/testcases/block/06_codeblock/no_newline_at_end_1.html +2 -0
- data/test/testcases/block/06_codeblock/no_newline_at_end_1.text +2 -0
- data/test/testcases/block/06_codeblock/with_ial.html +6 -0
- data/test/testcases/block/06_codeblock/with_ial.text +5 -0
- data/test/testcases/block/07_horizontal_rule/normal.html +0 -2
- data/test/testcases/block/07_horizontal_rule/normal.text +0 -2
- data/test/testcases/block/08_list/item_ial.html +1 -3
- data/test/testcases/block/08_list/lazy.html +39 -0
- data/test/testcases/block/08_list/lazy.text +29 -0
- data/test/testcases/block/08_list/list_and_others.html +5 -3
- data/test/testcases/block/08_list/list_and_others.text +1 -0
- data/test/testcases/block/08_list/other_first_element.html +2 -2
- data/test/testcases/block/08_list/other_first_element.text +1 -1
- data/test/testcases/block/08_list/simple_ul.html +0 -13
- data/test/testcases/block/08_list/simple_ul.text +0 -7
- data/test/testcases/block/08_list/special_cases.html +8 -31
- data/test/testcases/block/08_list/special_cases.text +2 -15
- data/test/testcases/block/09_html/comment.html +2 -2
- data/test/testcases/block/09_html/html_to_native/emphasis.html +2 -0
- data/test/testcases/block/09_html/html_to_native/emphasis.text +2 -0
- data/test/testcases/block/09_html/html_to_native/table_normal.html +2 -1
- data/test/testcases/block/09_html/html_to_native/table_simple.html +4 -2
- data/test/testcases/block/09_html/invalid_html_1.html +2 -0
- data/test/testcases/block/09_html/parse_as_raw.html +2 -2
- data/test/testcases/block/09_html/parse_as_span.html +1 -1
- data/test/testcases/block/09_html/simple.html +2 -0
- data/test/testcases/block/09_html/simple.html.19 +2 -0
- data/test/testcases/block/09_html/simple.text +2 -0
- data/test/testcases/block/11_ial/auto_id_and_ial.html +1 -1
- data/test/testcases/block/11_ial/simple.html +2 -3
- data/test/testcases/block/12_extension/comment.html +3 -1
- data/test/testcases/block/12_extension/comment.text +2 -1
- data/test/testcases/block/12_extension/ignored.html +5 -1
- data/test/testcases/block/12_extension/ignored.text +1 -1
- data/test/testcases/block/12_extension/nomarkdown.html +5 -1
- data/test/testcases/block/12_extension/nomarkdown.kramdown +20 -0
- data/test/testcases/block/12_extension/nomarkdown.latex +13 -0
- data/test/testcases/block/12_extension/nomarkdown.text +11 -1
- data/test/testcases/block/13_definition_list/item_ial.html +1 -3
- data/test/testcases/block/13_definition_list/item_ial.text +1 -1
- data/test/testcases/block/13_definition_list/simple.html +2 -2
- data/test/testcases/block/14_table/errors.html +5 -0
- data/test/testcases/block/14_table/errors.text +6 -0
- data/test/testcases/block/14_table/header.text +1 -1
- data/test/testcases/block/14_table/no_table.text +1 -1
- data/test/testcases/block/14_table/simple.html +78 -0
- data/test/testcases/block/14_table/simple.text +22 -0
- data/test/testcases/block/15_math/normal.html +11 -4
- data/test/testcases/block/15_math/normal.text +10 -0
- data/test/testcases/encoding.html +1 -1
- data/test/testcases/span/01_link/image_in_a.html +3 -3
- data/test/testcases/span/01_link/imagelinks.html +7 -7
- data/test/testcases/span/01_link/inline.html +11 -5
- data/test/testcases/span/01_link/inline.html.19 +11 -5
- data/test/testcases/span/01_link/inline.text +11 -5
- data/test/testcases/span/01_link/link_defs.html +2 -1
- data/test/testcases/span/01_link/link_defs.text +4 -0
- data/test/testcases/span/01_link/reference.html +3 -0
- data/test/testcases/span/01_link/reference.html.19 +3 -0
- data/test/testcases/span/01_link/reference.text +5 -0
- data/test/testcases/span/03_codespan/highlighting.html +1 -0
- data/test/testcases/span/03_codespan/highlighting.text +1 -0
- data/test/testcases/span/04_footnote/definitions.html +3 -0
- data/test/testcases/span/04_footnote/definitions.latex +3 -4
- data/test/testcases/span/04_footnote/definitions.text +6 -0
- data/test/testcases/span/04_footnote/footnote_nr.latex +1 -5
- data/test/testcases/span/04_footnote/markers.latex +5 -14
- data/test/testcases/span/05_html/markdown_attr.html +1 -1
- data/test/testcases/span/05_html/markdown_attr.text +1 -1
- data/test/testcases/span/05_html/normal.html +5 -3
- data/test/testcases/span/05_html/normal.text +2 -0
- data/test/testcases/span/escaped_chars/normal.html +2 -0
- data/test/testcases/span/escaped_chars/normal.text +2 -0
- data/test/testcases/span/extension/comment.html +2 -2
- data/test/testcases/span/extension/ignored.html +1 -1
- data/test/testcases/span/text_substitutions/typography.html +1 -1
- data/test/testcases/span/text_substitutions/typography.html.19 +1 -1
- data/test/testcases/span/text_substitutions/typography.text +1 -1
- metadata +20 -5
- data/test/testcases/block/05_blockquote/only_first_quoted.html +0 -8
- data/test/testcases/block/05_blockquote/only_first_quoted.text +0 -4
data/Rakefile
CHANGED
|
@@ -236,7 +236,7 @@ EOF
|
|
|
236
236
|
|
|
237
237
|
desc "Upload the website to Rubyforge"
|
|
238
238
|
task :publish_website => ['doc'] do
|
|
239
|
-
sh "rsync -avc --delete --exclude 'wiki' --exclude 'robots.txt' htmldoc/ gettalong@rubyforge.org:/var/www/gforge-projects/kramdown/"
|
|
239
|
+
sh "rsync -avc --delete --exclude 'wiki' --exclude 'js/jsMath' --exclude 'robots.txt' htmldoc/ gettalong@rubyforge.org:/var/www/gforge-projects/kramdown/"
|
|
240
240
|
end
|
|
241
241
|
|
|
242
242
|
|
|
@@ -306,7 +306,7 @@ if defined? Webgen
|
|
|
306
306
|
lines = term.desc.split(/\n/)
|
|
307
307
|
first = lines.shift
|
|
308
308
|
rest = lines[0..-2].collect {|l| " " + l}.join("\n")
|
|
309
|
-
"`#{term.name}`\n: #{first}\n#{rest}"
|
|
309
|
+
"`#{term.name}`\n: #{first}\n#{rest}\n\n"
|
|
310
310
|
end.join("\n")
|
|
311
311
|
end
|
|
312
312
|
|
data/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.
|
|
1
|
+
0.11.0
|
data/data/kramdown/document.html
CHANGED
|
@@ -1,7 +1,16 @@
|
|
|
1
1
|
<html>
|
|
2
2
|
<head>
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
<%
|
|
4
|
+
extend ::Kramdown::Utils::HTML
|
|
5
|
+
title = ''
|
|
6
|
+
h = @doc.tree.children.find {|c| c.type == :header}
|
|
7
|
+
if h
|
|
8
|
+
collector = lambda {|c| c.children.collect {|cc| cc.type == :text ? escape_html(cc.value, :text) : collector.call(cc)}.join('')}
|
|
9
|
+
title = collector.call(h)
|
|
10
|
+
end
|
|
11
|
+
%>
|
|
12
|
+
<title><%= title %></title>
|
|
13
|
+
<meta name="generator" content="kramdown <%= ::Kramdown::VERSION %>" />
|
|
5
14
|
</head>
|
|
6
15
|
<body>
|
|
7
16
|
<%= @body %>
|
data/doc/default.template
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
5
5
|
<meta name="author" content="Thomas Leitner" />
|
|
6
|
-
<meta name="copyright" content="2009 Thomas Leitner" />
|
|
6
|
+
<meta name="copyright" content="2009-2010 Thomas Leitner" />
|
|
7
7
|
<meta name="description" content="kramdown is a fast, pure-Ruby Markdown-superset converter" />
|
|
8
8
|
<meta name="keywords" content="ruby, kramdown, markdown, text markup" />
|
|
9
9
|
<link href="{relocatable: default.css}" type="text/css" rel="stylesheet" media="screen,projection" />
|
|
10
10
|
<link href="{relocatable: news.atom}" type="application/atom+xml" rel="alternate" />
|
|
11
|
-
<script src="
|
|
11
|
+
<script src="http://kramdown.rubyforge.org/js/jsMath/easy/load.js" type="text/javascript"></script>
|
|
12
12
|
<title>{title:} | kramdown</title>
|
|
13
13
|
</head>
|
|
14
14
|
<body>
|
data/doc/index.page
CHANGED
|
@@ -72,7 +72,6 @@ Markdown implementations because kramdown borrowed many ideas from existing pack
|
|
|
72
72
|
|
|
73
73
|
[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
|
|
74
74
|
[Maruku]: http://maruku.rubyforge.org
|
|
75
|
-
[RedCloth]: http://whytheluckystiff.net/ruby/redcloth/
|
|
76
75
|
[BlueCloth]: http://www.deveiate.org/projects/BlueCloth
|
|
77
76
|
|
|
78
77
|
|
|
@@ -89,7 +88,7 @@ It is probably the fastest pure-Ruby Markdown converter available (June 2010), b
|
|
|
89
88
|
than [Maruku] and about 9x faster than [BlueFeather].
|
|
90
89
|
|
|
91
90
|
<p class="a-center">
|
|
92
|
-
The latest version of kramdown is <b>0.
|
|
91
|
+
The latest version of kramdown is <b>0.11.0</b> and it was released on <b>2010-10-01</b>.
|
|
93
92
|
</p>
|
|
94
93
|
|
|
95
94
|
[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
|
data/doc/quickref.page
CHANGED
|
@@ -310,7 +310,7 @@ This can contain only *span* level elements.
|
|
|
310
310
|
|
|
311
311
|
## Block Attributes
|
|
312
312
|
|
|
313
|
-
{kdlink: {oid: block-
|
|
313
|
+
{kdlink: {oid: block-ials, part: "block IALs"}}
|
|
314
314
|
{kdlink: {oid: attribute-list-definitions, part: "ALDs"}}
|
|
315
315
|
|
|
316
316
|
You can assign any attribute to a block level element. Just directly follow the block with a *block
|
|
@@ -553,7 +553,7 @@ red</span>.
|
|
|
553
553
|
|
|
554
554
|
## Inline Attributes
|
|
555
555
|
|
|
556
|
-
{kdlink: {oid: span-
|
|
556
|
+
{kdlink: {oid: span-ials, part: "span IALs"}}
|
|
557
557
|
|
|
558
558
|
As with a block level element you can assign any attribute to a span level elements using a *span
|
|
559
559
|
inline attribute list* (or short: span IAL). A span IAL has the same syntax as a block IAL and must
|
data/doc/syntax.page
CHANGED
|
@@ -26,8 +26,9 @@ document is converted.
|
|
|
26
26
|
## Source Text Formatting
|
|
27
27
|
|
|
28
28
|
A kramdown document may be in any encoding, for example ASCII, UTF-8 or ISO-8859-1, and the output
|
|
29
|
-
will have the same encoding as the source.
|
|
30
|
-
|
|
29
|
+
will have the same encoding as the source.
|
|
30
|
+
|
|
31
|
+
The document consists of two types of elements, block level elements and span level elements:
|
|
31
32
|
|
|
32
33
|
* Block level elements define the main structure of the content, for example, what part of the text
|
|
33
34
|
should be a paragraph, a list, a blockquote and so on.
|
|
@@ -43,6 +44,32 @@ beginning of a kramdown document opens up the default indentation level which be
|
|
|
43
44
|
column of the text.
|
|
44
45
|
|
|
45
46
|
|
|
47
|
+
## Line Wrapping
|
|
48
|
+
|
|
49
|
+
Some lightweight markup syntax don't work well in environments where lines are hard-wrapped. For
|
|
50
|
+
example, this is the case with many email programs. Therefore kramdown allows content like
|
|
51
|
+
paragraphs or blockquotes to be hard-wrapped, i.e. broken across lines. This is sometimes referred
|
|
52
|
+
to as "lazy syntax" since the indentation or line prefix required for the first line of content is
|
|
53
|
+
not required for the consecutive lines.
|
|
54
|
+
|
|
55
|
+
Block level elements that support line wrapping always end when one of the following conditions is
|
|
56
|
+
encountered:
|
|
57
|
+
|
|
58
|
+
* a [blank line](#blank-lines), an [EOB marker line](#eob-marker), a [block IAL](#block-ials) or the
|
|
59
|
+
end of the document (i.e. a [block boundary](#block-boundaries)),
|
|
60
|
+
|
|
61
|
+
* or an [HTML block](#html-blocks).
|
|
62
|
+
|
|
63
|
+
Line wrapping is allowed throughout a kramdown document. There is one exception, however:
|
|
64
|
+
[headers](#headers) may not be wrapped across lines. This is not an issue in most situations since
|
|
65
|
+
headers normally fit on one line. If a header text gets too long for one line, use HTML syntax
|
|
66
|
+
instead.
|
|
67
|
+
|
|
68
|
+
**Note** that it is **NOT** recommended to use lazy syntax to write a kramdown document. The
|
|
69
|
+
flexibility that the kramdown syntax offers due to the issue of line wrapping hinders readability
|
|
70
|
+
and should therefore not be used.
|
|
71
|
+
|
|
72
|
+
|
|
46
73
|
### Usage of Tabs
|
|
47
74
|
|
|
48
75
|
kramdown assumes that tab stops are set at multiples of four. This is especially important when
|
|
@@ -58,7 +85,7 @@ when converting a kramdown document to HTML one needs to take care of the charac
|
|
|
58
85
|
depending on the output format.
|
|
59
86
|
|
|
60
87
|
This means, for example, that you can just use `<`, `>` and `&` in a kramdown document and need not
|
|
61
|
-
think about when to use their HTML entity counterparts. However, if you *do use* HTML
|
|
88
|
+
think about when to use their HTML entity counterparts. However, if you *do use* HTML entities or
|
|
62
89
|
HTML tags which use one of the characters, the result will be correct nonetheless!
|
|
63
90
|
|
|
64
91
|
Since kramdown also uses some characters to mark-up the text, there needs to be a way to escape
|
|
@@ -75,6 +102,7 @@ Following is a list of all the characters (character sequences) that can be esca
|
|
|
75
102
|
_ underscore
|
|
76
103
|
+ plus
|
|
77
104
|
- minus
|
|
105
|
+
= equal sign
|
|
78
106
|
` backtick
|
|
79
107
|
()[]{} left and right parens/brackets/braces
|
|
80
108
|
# hash
|
|
@@ -88,6 +116,21 @@ Following is a list of all the characters (character sequences) that can be esca
|
|
|
88
116
|
$ dollar sign
|
|
89
117
|
|
|
90
118
|
|
|
119
|
+
## Block Boundaries
|
|
120
|
+
|
|
121
|
+
Some block level elements have to start and/or end on so called block boundaries, as stated in their
|
|
122
|
+
documentation. There are two cases where block boundaries come into play:
|
|
123
|
+
|
|
124
|
+
* If a block level element has to start on a block boundary, it has to be preceded by either a
|
|
125
|
+
[blank line](#blank-lines), an [EOB marker](#eob-marker), a [block IAL](#block-ials) or it has to
|
|
126
|
+
be the first element.
|
|
127
|
+
|
|
128
|
+
* If a block level element has to end on a block boundary, it has to be followed by either a [blank
|
|
129
|
+
line](#blank-lines), an [EOB marker](#eob-marker), a [block IAL](#block-ials) or it has to be the
|
|
130
|
+
last element.
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
|
|
91
134
|
# Structural Elements
|
|
92
135
|
|
|
93
136
|
All structural elements are block level elements and they are used to structure the content. They
|
|
@@ -98,30 +141,36 @@ can mark up some text as, for example, a simple paragraph, a quote or as a list
|
|
|
98
141
|
|
|
99
142
|
Any line that just contains white space characters such as spaces and tabs is considered a blank
|
|
100
143
|
line by kramdown. One or more consecutive blank lines are handled as one empty blank line. Blank
|
|
101
|
-
lines are
|
|
102
|
-
|
|
103
|
-
meaning:
|
|
144
|
+
lines are used to separate block level elements from each other and in this case they don't have
|
|
145
|
+
semantic meaning. However, there are some cases where blank lines do have a semantic meaning:
|
|
104
146
|
|
|
105
|
-
* When used in paragraphs -- see the [paragraphs section](#paragraphs)
|
|
106
147
|
* When used in headers -- see the [headers section](#headers)
|
|
148
|
+
* When used in code blocks -- see the [code blocks section](#code-blocks)
|
|
107
149
|
* When used in lists -- see the [lists section](#lists)
|
|
150
|
+
* When used in math blocks -- see the [math blocks section](#math-blocks)
|
|
151
|
+
* When used for elements that have to start/end on [block boundaries](#block-boundaries)
|
|
108
152
|
|
|
109
153
|
|
|
110
154
|
## Paragraphs
|
|
111
155
|
|
|
112
156
|
Paragraphs are the most used block level elements. One or more consecutive lines of text are
|
|
113
|
-
interpreted as one paragraph.
|
|
114
|
-
|
|
115
|
-
line
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
157
|
+
interpreted as one paragraph. The first line of a paragraph may be indented up to three spaces, the
|
|
158
|
+
other lines can have any amount of indentation because paragraphs support [line
|
|
159
|
+
wrapping](#line-wrapping). In addition to the rules outlined in the section about line wrapping, a
|
|
160
|
+
paragraph ends when a [definition list line](#definition-lists) is encountered.
|
|
161
|
+
|
|
162
|
+
You can separate two consecutive paragraphs from each other by using one or more blank lines. Notice
|
|
163
|
+
that a line break in the source does not mean a line break in the output (due to the [lazy
|
|
164
|
+
syntax](#line-wrapping))!. If you want to have an explicit line break (i.e. a `<br />` tag) you need
|
|
165
|
+
to end a line with two or more spaces or two backslashes! Note, however, that a line break on the
|
|
166
|
+
last text line of a paragraph is not possible and will be ignored. Leading and trailing spaces will
|
|
167
|
+
be stripped from the paragraph text.
|
|
119
168
|
|
|
120
169
|
The following gives you an example of how paragraphs look like:
|
|
121
170
|
|
|
122
171
|
This para line starts at the first column. However,
|
|
123
|
-
|
|
124
|
-
|
|
172
|
+
the following lines can be indented any number of spaces/tabs.
|
|
173
|
+
The para continues here.
|
|
125
174
|
|
|
126
175
|
This is another paragraph, not connected to the above one. But
|
|
127
176
|
with a hard line break. \\
|
|
@@ -136,12 +185,12 @@ single document.
|
|
|
136
185
|
|
|
137
186
|
### Setext Style
|
|
138
187
|
|
|
139
|
-
Setext style headers
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
188
|
+
Setext style headers have to start on a [block boundary](#block-boundaries) with a line of text (the
|
|
189
|
+
header text) and a line with only equal signs (for a first level header) or dashes (for a second
|
|
190
|
+
level header). The header text may be indented up to three spaces but any leading or trailing spaces
|
|
191
|
+
are stripped from the header text. The amount of equal signs or dashes is not significant, just one
|
|
192
|
+
is enough but more may look better. The equal signs or dashes have to begin at the first column. For
|
|
193
|
+
example:
|
|
145
194
|
|
|
146
195
|
First level header
|
|
147
196
|
==================
|
|
@@ -152,7 +201,8 @@ signs or dashes have to begin at the first column. For example:
|
|
|
152
201
|
Other first level header
|
|
153
202
|
=
|
|
154
203
|
|
|
155
|
-
|
|
204
|
+
Since Setext headers start on block boundaries, this means in most situations that they have to be
|
|
205
|
+
preceded by a blank line. However, blank lines are not necessary after a Setext header:
|
|
156
206
|
|
|
157
207
|
This is a normal
|
|
158
208
|
paragraph.
|
|
@@ -167,7 +217,7 @@ As mentioned you need to insert a blank line before (but not necessarily after)
|
|
|
167
217
|
------------
|
|
168
218
|
|
|
169
219
|
However, it is generally a good idea to also use a blank line after a Setext header because it looks
|
|
170
|
-
more appropriate.
|
|
220
|
+
more appropriate and eases reading of the document.
|
|
171
221
|
|
|
172
222
|
> The original Markdown syntax allows one to omit the blank line before a Setext header. However,
|
|
173
223
|
> this leads to ambiguities and makes reading the document harder than necessary. Therefore it is
|
|
@@ -186,13 +236,12 @@ the case. The general rule is that Setext headers are processed before horizonta
|
|
|
186
236
|
|
|
187
237
|
### atx Style
|
|
188
238
|
|
|
189
|
-
atx style headers
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
the header text. For example:
|
|
239
|
+
atx style headers have to start on a [block boundary](#block-boundaries) with a line that contains
|
|
240
|
+
one or more hash characters and then the header text. No spaces are allowed before the hash
|
|
241
|
+
characters. The number of hash characters specifies the heading level: one hash character gives you
|
|
242
|
+
a first level heading, two a second level heading and so on until the maximum of six hash characters
|
|
243
|
+
for a sixth level heading. You may optionally use any number of hashes at the end of the line to
|
|
244
|
+
close the header. Any leading or trailing spaces are stripped from the header text. For example:
|
|
196
245
|
|
|
197
246
|
# First level header
|
|
198
247
|
|
|
@@ -226,20 +275,25 @@ trailing hashes. For example:
|
|
|
226
275
|
## Blockquotes
|
|
227
276
|
|
|
228
277
|
A blockquote is started using the `>` marker followed by an optional space and the content of the
|
|
229
|
-
blockquote. The marker itself may be indented up to three spaces. All following lines
|
|
230
|
-
started with the blockquote marker
|
|
231
|
-
|
|
232
|
-
|
|
278
|
+
blockquote. The marker itself may be indented up to three spaces. All following lines, whether they
|
|
279
|
+
are started with the blockquote marker or just contain text, belong to the blockquote because
|
|
280
|
+
blockquotes support [line wrapping](#line-wrapping).
|
|
281
|
+
|
|
282
|
+
The contents of a blockquote are block level elements. This means that if you are just using text as
|
|
283
|
+
content that it will be wrapped in a paragraph. For example, the following gives you one blockquote
|
|
284
|
+
with two paragraphs in it:
|
|
233
285
|
|
|
234
286
|
> This is a blockquote.
|
|
235
|
-
>on multiple lines
|
|
287
|
+
> on multiple lines
|
|
288
|
+
that may be lazy.
|
|
236
289
|
>
|
|
237
290
|
> This is the second paragraph.
|
|
238
291
|
|
|
239
292
|
Since the contents of a blockquote are block level elements, you can nest blockquotes and use other
|
|
240
|
-
block level elements:
|
|
293
|
+
block level elements (this is also the reason why blockquotes need to support line wrapping):
|
|
241
294
|
|
|
242
295
|
> This is a paragraph.
|
|
296
|
+
>
|
|
243
297
|
> > A nested blockquote.
|
|
244
298
|
>
|
|
245
299
|
> ## Headers work
|
|
@@ -256,17 +310,16 @@ will have to be indented with five spaces or one space and one tab, like this:
|
|
|
256
310
|
>
|
|
257
311
|
> ruby -e 'puts :works'
|
|
258
312
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
>
|
|
263
|
-
|
|
264
|
-
>
|
|
265
|
-
>
|
|
266
|
-
|
|
267
|
-
>
|
|
268
|
-
>
|
|
269
|
-
{: .markdown-difference}
|
|
313
|
+
[Line wrapping](#line-wrapping) allows one to be lazy but hinders readability and should therefore
|
|
314
|
+
be avoided, especially with blockquotes. Here is an example of using blockquotes with line wrapping:
|
|
315
|
+
|
|
316
|
+
> This is a paragraph inside
|
|
317
|
+
a blockquote.
|
|
318
|
+
>
|
|
319
|
+
> > This is a nested paragraph
|
|
320
|
+
that continues here
|
|
321
|
+
> and here
|
|
322
|
+
> > and here
|
|
270
323
|
|
|
271
324
|
|
|
272
325
|
## Code Blocks
|
|
@@ -274,12 +327,19 @@ will have to be indented with five spaces or one space and one tab, like this:
|
|
|
274
327
|
Code blocks can be used to represent verbatim text like markup, HTML or a program fragment because
|
|
275
328
|
no syntax is parsed within a code block.
|
|
276
329
|
|
|
277
|
-
### Standard Code
|
|
330
|
+
### Standard Code Blocks
|
|
278
331
|
|
|
279
332
|
A code block can be started by using four spaces or one tab and then the text of the code block. All
|
|
280
|
-
following lines
|
|
281
|
-
|
|
282
|
-
|
|
333
|
+
following lines containing text, whether they adhere to this syntax or not, belong to the code block
|
|
334
|
+
because code blocks support [line wrapping](#line-wrapping)). A wrapped code line is automatically
|
|
335
|
+
appended to the preceding code line by substituting the line break with a space character. The
|
|
336
|
+
indentation (four spaces or one tab) is stripped from each line of the code block.
|
|
337
|
+
|
|
338
|
+
> The original Markdown syntax does not allow line wrapping in code blocks.
|
|
339
|
+
{: .markdown-difference}
|
|
340
|
+
|
|
341
|
+
Note that consecutive code blocks that are only separate by [blank lines](#blank-lines) are merged
|
|
342
|
+
together into one code block:
|
|
283
343
|
|
|
284
344
|
Here comes some code
|
|
285
345
|
|
|
@@ -292,7 +352,7 @@ marker](#eob-marker) to separate the two:
|
|
|
292
352
|
^
|
|
293
353
|
This one is separate.
|
|
294
354
|
|
|
295
|
-
### Fenced Code
|
|
355
|
+
### Fenced Code Blocks
|
|
296
356
|
|
|
297
357
|
> This alternative syntax is not part of the original Markdown syntax. The idea and syntax comes
|
|
298
358
|
> from the [PHP Markdown Extra] package.
|
|
@@ -358,22 +418,36 @@ The following gives you an unordered list and an ordered list:
|
|
|
358
418
|
The first list marker in a list may be indented up to three spaces. The column number of the first
|
|
359
419
|
non-space character which appears after the list item marker on the same line specifies the
|
|
360
420
|
indentation that has to be used for the following lines of content of the list item. If there is no
|
|
361
|
-
such character, the indentation that needs to be used is four spaces or one tab.
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
421
|
+
such character, the indentation that needs to be used is four spaces or one tab. Indented lines may
|
|
422
|
+
be followed by lines containg text with any amount of indentation due to [line
|
|
423
|
+
wrapping](#line-wrapping). Note, however, that in addition to the rules outlined in the section
|
|
424
|
+
about line wrapping, a list item also ends when a line with another list item marker is encountered
|
|
425
|
+
-- see the next paragraph.
|
|
426
|
+
|
|
427
|
+
The indentation is stripped from the content and the content (note that the content naturally also
|
|
428
|
+
contains the content of the line with the item marker) is processed as text containing block level
|
|
429
|
+
elements. All other list markers in the list may be indented up to three spaces or the number of
|
|
430
|
+
spaces used for the indentation of the last list item minus one, whichever number is smaller. For
|
|
431
|
+
example:
|
|
367
432
|
|
|
368
433
|
* This is the first line. Since the first non-space characters appears in column 3, all other
|
|
369
|
-
lines have to be indented 2 spaces
|
|
370
|
-
|
|
434
|
+
indented lines have to be indented 2 spaces.
|
|
435
|
+
However, one could be lazy and not indent a line but this is not recommened.
|
|
371
436
|
* This is the another item of the list. It uses a different number of spaces for
|
|
372
|
-
|
|
373
|
-
* The list item marker is indented 3 spaces which is allowed but should also be avoided
|
|
437
|
+
indentation which is okay but should generally be avoided.
|
|
438
|
+
* The list item marker is indented 3 spaces which is allowed but should also be avoided and
|
|
439
|
+
starts the third list item. Note that the lazy line in the second list item may make you
|
|
440
|
+
believe that this is a sub-list which it isn't! So avoid being lazy!
|
|
374
441
|
|
|
375
442
|
So, while the above is possible and creates one list with three items, it is not advised to use
|
|
376
|
-
different (marker and list content) indents for same level list items!
|
|
443
|
+
different (marker and list content) indents for same level list items as well as lazy indentation!
|
|
444
|
+
It is much better to write such a list in the following way:
|
|
445
|
+
|
|
446
|
+
* This is the first list item bla blabla blabla blabla blabla blabla blabla blabla blabla blabla
|
|
447
|
+
blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla
|
|
448
|
+
blabla blabla blabla bla
|
|
449
|
+
* This is the another item of the list. bla blabla blabla blabla blabla blabla blabla blabla
|
|
450
|
+
blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla blabla bla
|
|
377
451
|
|
|
378
452
|
> The original Markdown syntax also allows you to indent the marker, however, the behaviour of what
|
|
379
453
|
> happens with the list items is not clearly specified and may surprise you.
|
|
@@ -388,9 +462,9 @@ example:
|
|
|
388
462
|
* Using a tab to indent this line, the tab only counts as three spaces and therefore the
|
|
389
463
|
overall indentation is four spaces.
|
|
390
464
|
|
|
391
|
-
1. The tab after the marker counts here as
|
|
392
|
-
is three spaces and the marker itself takes two characters, the overall
|
|
393
|
-
needed for the following lines is eight spaces or two tabs.
|
|
465
|
+
1. The tab after the marker counts here as three spaces. Since the indentation of the
|
|
466
|
+
marker is three spaces and the marker itself takes two characters, the overall
|
|
467
|
+
indentation needed for the following lines is eight spaces or two tabs.
|
|
394
468
|
|
|
395
469
|
It is clear that you might get unexpected results if you mix tabs and spaces or if you don't have
|
|
396
470
|
the tab stops set to multiples of four in your editor! Therefore this should be avoided!
|
|
@@ -443,6 +517,7 @@ Since the content of a list item can contain block level elements, you can do th
|
|
|
443
517
|
A second paragraph
|
|
444
518
|
|
|
445
519
|
* nested list
|
|
520
|
+
|
|
446
521
|
> blockquote
|
|
447
522
|
|
|
448
523
|
* Second item
|
|
@@ -469,17 +544,6 @@ Note that the list marker needs to be followed with at least one space or tab! O
|
|
|
469
544
|
not recognized as the start of a list item but interpreted as a paragraph containing the list
|
|
470
545
|
marker.
|
|
471
546
|
|
|
472
|
-
> The original Markdown syntax allows you to be lazy when you just use text for a list item. So the
|
|
473
|
-
> following is possible with Markdown:
|
|
474
|
-
>
|
|
475
|
-
> * First list item
|
|
476
|
-
> continued here
|
|
477
|
-
> * Second list item
|
|
478
|
-
> continued here.
|
|
479
|
-
>
|
|
480
|
-
> This kind of syntax is disallowed in kramdown.
|
|
481
|
-
{: .markdown-difference}
|
|
482
|
-
|
|
483
547
|
If you want to have one list directly after another one (both with the same list type, i.e. ordered
|
|
484
548
|
or unordered), you need to use an EOB marker to separate the two:
|
|
485
549
|
|
|
@@ -487,16 +551,9 @@ or unordered), you need to use an EOB marker to separate the two:
|
|
|
487
551
|
^
|
|
488
552
|
* List two
|
|
489
553
|
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
I have read the book
|
|
494
|
-
1984. It was great
|
|
495
|
-
- others say that, too!
|
|
496
|
-
|
|
497
|
-
Therefore you have to insert a blank line after a paragraph if you want to follow the paragraph with
|
|
498
|
-
a list. The only exception to this rule is when you want to create a compact nested list, i.e. a
|
|
499
|
-
list where the text is not wrapped in paragraphs:
|
|
554
|
+
Since paragraphs support [line wrapping](#line-wrapping), it would usually not be possible to create
|
|
555
|
+
compact nested list, i.e. a list where the text is not wrapped in paragraphs because there is no
|
|
556
|
+
blank line but a sub list after it:
|
|
500
557
|
|
|
501
558
|
* This is just text.
|
|
502
559
|
* this is a sub list item
|
|
@@ -505,9 +562,11 @@ list where the text is not wrapped in paragraphs:
|
|
|
505
562
|
spanning two lines
|
|
506
563
|
* this is a nested list item.
|
|
507
564
|
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
565
|
+
However, this is an often used syntax and is therefore support by kramdown.
|
|
566
|
+
|
|
567
|
+
If you want to start a paragraph with something that looks like a list item marker, you need to
|
|
568
|
+
escape it. This is done by escaping the period in an ordered list or the list item marker in an
|
|
569
|
+
unordered list:
|
|
511
570
|
|
|
512
571
|
1984\. It was great
|
|
513
572
|
\- others say that, too!
|
|
@@ -548,26 +607,29 @@ The following is a simple definition list:
|
|
|
548
607
|
|
|
549
608
|
The column number of the first non-space character which appears after a definition marker on the
|
|
550
609
|
same line specifies the indentation that has to be used for the following lines of the definition.
|
|
551
|
-
If there is no such character, the indentation that needs to be used is four spaces or one tab.
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
the
|
|
610
|
+
If there is no such character, the indentation that needs to be used is four spaces or one tab.
|
|
611
|
+
Indented lines may be followed by lines containg text with any amount of indentation due to [line
|
|
612
|
+
wrapping](#line-wrapping). Note, however, that in addition to the rules outlined in the section
|
|
613
|
+
about line wrapping, a list item also ends when a line with another definition marker is encountered.
|
|
614
|
+
|
|
615
|
+
The indentation is stripped from the definition and it (note that the definition naturally also
|
|
616
|
+
contains the content of the line with the definition marker) is processed as text containing block
|
|
617
|
+
level elements. If there is more than one definition, all other definition markers for the term may
|
|
618
|
+
be indented up to three spaces or the number of spaces used for the indentation of the last
|
|
619
|
+
definition minus one, whichever number is smaller. For example:
|
|
558
620
|
|
|
559
621
|
definition term 1
|
|
560
622
|
definition term 2
|
|
561
623
|
: This is the first line. Since the first non-space characters appears in column 3, all other
|
|
562
|
-
|
|
563
|
-
that the lines belong to the definition.
|
|
624
|
+
lines have to be indented 2 spaces (or lazy syntax may be used after an indented line). This
|
|
625
|
+
tells kramdown that the lines belong to the definition.
|
|
564
626
|
: This is the another definition for the same term. It uses a different number of spaces
|
|
565
627
|
for indentation which is okay but should generally be avoided.
|
|
566
628
|
: The definition marker is indented 3 spaces which is allowed but should also be avoided.
|
|
567
629
|
|
|
568
630
|
So, while the above is possible and creates a definition list with two terms and three definitions
|
|
569
631
|
for them, it is not advised to use different (definition marker and definition) indents in the same
|
|
570
|
-
definition list!
|
|
632
|
+
definition list as well as lazy indentation!
|
|
571
633
|
|
|
572
634
|
The definition for a term is made up of text and/or block level elements. If a definition is *not*
|
|
573
635
|
preceded by a blank line, the first part of the definition will just be text if it would be a
|
|
@@ -595,13 +657,19 @@ Sometimes one wants to include simple tabular data in a kramdown document for wh
|
|
|
595
657
|
full-blown HTML table is just too much. kramdown supports this with a simple syntax for ASCII
|
|
596
658
|
tables.
|
|
597
659
|
|
|
598
|
-
|
|
660
|
+
Tables can be created with or without a leading pipe character: If the first line of a table
|
|
661
|
+
contains a pipe character at the start of the line (optionally indented up to three spaces), then
|
|
662
|
+
all leading pipe characters (i.e. pipe characters that are only preceded by whitespace) are ignored
|
|
663
|
+
on all table lines. Otherwise they are not ignored and count when dividing a table line into table
|
|
664
|
+
cells.
|
|
665
|
+
|
|
666
|
+
There are four different line types that can be used in a table:
|
|
599
667
|
|
|
600
668
|
* *Table rows* define the content of a table.
|
|
601
669
|
|
|
602
|
-
A table row is
|
|
603
|
-
|
|
604
|
-
|
|
670
|
+
A table row is any line that contains at least one pipe character and is not identified as any
|
|
671
|
+
other type of table line! The table row is divided into indivdual table cells by pipe characters.
|
|
672
|
+
An optional trailing pipe character is ignored.
|
|
605
673
|
|
|
606
674
|
Header rows, footer rows and normal rows are all done using these table rows. Table cells can only
|
|
607
675
|
contain a single line of text, no multiline text is supported. The text of a table cell is parsed
|
|
@@ -613,13 +681,14 @@ There are three different text line types that can be used in a table:
|
|
|
613
681
|
| First cell|Second cell|Third cell
|
|
614
682
|
| First | Second | Third |
|
|
615
683
|
|
|
684
|
+
First | Second | | Fourth |
|
|
685
|
+
|
|
616
686
|
* *Separator lines* are used to split the table body into multiple body parts.
|
|
617
687
|
|
|
618
|
-
A separator line is
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
as one separator line.
|
|
688
|
+
A separator line is any line that contains only pipes, dashes, pluses, colons and spaces and which
|
|
689
|
+
contains at least one dash and one pipe character. The pipe and plus characters can be used to
|
|
690
|
+
visually separate columns although this is not needed. Multiple separator lines after another are
|
|
691
|
+
treated as one separator line.
|
|
623
692
|
|
|
624
693
|
Here are some example separator lines:
|
|
625
694
|
|
|
@@ -628,6 +697,7 @@ There are three different text line types that can be used in a table:
|
|
|
628
697
|
|---------|
|
|
629
698
|
|-
|
|
630
699
|
| :-----: |
|
|
700
|
+
-|-
|
|
631
701
|
|
|
632
702
|
* The first separator line after at least one table row is treated specially, namely as *header
|
|
633
703
|
separator line*. It is used to demarcate header rows from normal table rows and/or to set column
|
|
@@ -648,6 +718,7 @@ There are three different text line types that can be used in a table:
|
|
|
648
718
|
|---+---+---|
|
|
649
719
|
+ :-: |:------| ---:|
|
|
650
720
|
| :-: :- -: -
|
|
721
|
+
:-: | :-
|
|
651
722
|
|
|
652
723
|
* A *footer separator line* is used to demarcate footer rows from normal table rows. All table rows
|
|
653
724
|
below the footer separator line are considered to be footer rows.
|
|
@@ -677,12 +748,20 @@ Given the above components, a table is specified by
|
|
|
677
748
|
* optionally followed by a footer separator line and zero, one or more table rows and
|
|
678
749
|
* an optional trailing separator line.
|
|
679
750
|
|
|
751
|
+
Also note
|
|
752
|
+
|
|
753
|
+
* that the first line of a table must not have more than three spaces of indentation before the
|
|
754
|
+
first none space character,
|
|
755
|
+
* that each line of a table needs to have at least one not escaped pipe character so that kramdown
|
|
756
|
+
recognizes it as a line belonging to the table and
|
|
757
|
+
* that tables have to start and end on [block boundaries](#block-boundaries)!
|
|
758
|
+
|
|
680
759
|
> The table syntax differs from the one used in [PHP Markdown Extra] as follows:
|
|
681
760
|
>
|
|
682
|
-
> * kramdown tables have to begin with a pipe character, this is optional in [PHP Markdown Extra].
|
|
683
761
|
> * kramdown tables do not need to have a table header.
|
|
684
762
|
> * kramdown tables can be structured using separator lines.
|
|
685
763
|
> * kramdown tables can contain a table footer.
|
|
764
|
+
> * kramdown tables need to be separted from other block level elements.
|
|
686
765
|
{: .markdown-difference}
|
|
687
766
|
|
|
688
767
|
Here is an example for a kramdown table with a table header row, two table bodies and a table footer
|
|
@@ -741,11 +820,12 @@ three spaces. The following examples show different possibilities to create a ho
|
|
|
741
820
|
|
|
742
821
|
kramdown has built-in support for block and span level mathematics written in LaTeX.
|
|
743
822
|
|
|
744
|
-
A math block
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
823
|
+
A math block needs to start and end on [block boundaries](#block-boundaries). It is started using
|
|
824
|
+
two dollar signs, optionally indented up to three spaces. The math block continues until the next
|
|
825
|
+
two dollar signs (which may be on the same line or on one of the next lines) that appear at the end
|
|
826
|
+
of a line, i.e. they may only be followed by whitespace characters. The content of a math block has
|
|
827
|
+
to be valid LaTeX math. It is always wrapped inside a `\begin{displaymath}...\end{displaymath}`
|
|
828
|
+
enviroment except if it begins with a `\begin` statement.
|
|
749
829
|
|
|
750
830
|
The following kramdown fragment
|
|
751
831
|
|
|
@@ -954,8 +1034,8 @@ comments is not processed:
|
|
|
954
1034
|
|
|
955
1035
|
# Text Markup
|
|
956
1036
|
|
|
957
|
-
These elements are used inside block level elements to markup text
|
|
958
|
-
easily create links or apply emphasis to certain text parts.
|
|
1037
|
+
These elements are all span level elements and used inside block level elements to markup text
|
|
1038
|
+
fragments. For example, one can easily create links or apply emphasis to certain text parts.
|
|
959
1039
|
|
|
960
1040
|
Note that empty span level elements are not converted to empty HTML tags but are copied as-is to the
|
|
961
1041
|
output.
|
|
@@ -991,7 +1071,7 @@ single or double quotes preceded by at least one space) in normal parentheses. F
|
|
|
991
1071
|
|
|
992
1072
|
This is [a link](http://rubyforge.org) to a page.
|
|
993
1073
|
A [link](../test "local URI") can also have a title.
|
|
994
|
-
And [spaces](
|
|
1074
|
+
And [spaces](link with spaces.html)!
|
|
995
1075
|
|
|
996
1076
|
Notes:
|
|
997
1077
|
|
|
@@ -999,10 +1079,9 @@ Notes:
|
|
|
999
1079
|
However, if you use square brackets within the link text, you have to either properly nest them or
|
|
1000
1080
|
to escape them. It is not possible to create nested links!
|
|
1001
1081
|
|
|
1002
|
-
* The link URL must not contain
|
|
1003
|
-
title is specified, or the link URL must be contained in angle brackets
|
|
1004
|
-
incorrectly nested parentheses are allowed).
|
|
1005
|
-
if no title is specified, no spaces are allowed between the link URL and the closing parenthesis.
|
|
1082
|
+
* The link URL must not contain single or double quotes and it has to contain properly nested
|
|
1083
|
+
parentheses if no title is specified, or the link URL must be contained in angle brackets
|
|
1084
|
+
(incorrectly nested parentheses are allowed).
|
|
1006
1085
|
|
|
1007
1086
|
* The link title may not contain its delimiters and may not be empty.
|
|
1008
1087
|
|
|
@@ -1030,15 +1109,15 @@ definition looks like this:
|
|
|
1030
1109
|
|
|
1031
1110
|
[linkid]: http://www.example.com/ "Optional Title"
|
|
1032
1111
|
|
|
1033
|
-
> Link definitions are, despite being described here, block level elements.
|
|
1112
|
+
> Link definitions are, despite being described here, non-content block level elements.
|
|
1034
1113
|
{: .information}
|
|
1035
1114
|
|
|
1036
1115
|
The link definition has the following structure:
|
|
1037
1116
|
|
|
1038
1117
|
* The link identifier in square brackets, optionally indented up to three spaces,
|
|
1039
1118
|
* then a colon and one or more spaces/tabs,
|
|
1040
|
-
* then the link URL which must not contain any
|
|
1041
|
-
|
|
1119
|
+
* then the link URL which must not contain any single or double quotes and which must contain at
|
|
1120
|
+
least one non-space character, or a left angle bracket, the link URL and a right angle bracket,
|
|
1042
1121
|
* then optionally the title in single or double quotes, separated from the link URL by one or more
|
|
1043
1122
|
spaces or on the next line by itself indented any number of spaces/tabs.
|
|
1044
1123
|
|
|
@@ -1206,10 +1285,11 @@ A footnote definition is used to define the content of a footnote and has the fo
|
|
|
1206
1285
|
* The footnote name in square brackets, optionally indented up to three spaces,
|
|
1207
1286
|
* then a colon and one or more optional spaces,
|
|
1208
1287
|
* then the text of the footnote
|
|
1209
|
-
* and optionally more text on the following lines which have
|
|
1210
|
-
one tab
|
|
1288
|
+
* and optionally more text on the following lines which have to follow the syntax for [standard code
|
|
1289
|
+
blocks](#standard-code-blocks) (the leading four spaces/one tab are naturally stripped from the
|
|
1290
|
+
text)
|
|
1211
1291
|
|
|
1212
|
-
> Footnote definitions are, despite being described here, block level elements.
|
|
1292
|
+
> Footnote definitions are, despite being described here, non-content block level elements.
|
|
1213
1293
|
{: .information}
|
|
1214
1294
|
|
|
1215
1295
|
The whole footnote content is treated like block level text and can therefore contain any valid
|
|
@@ -1233,8 +1313,8 @@ Here are some example footnote definitions:
|
|
|
1233
1313
|
|
|
1234
1314
|
It does not matter where you put a footnote definition in a kramdown document; the content of all
|
|
1235
1315
|
referenced footnote definitions will be placed at the end of the kramdown document. Not referenced
|
|
1236
|
-
|
|
1237
|
-
|
|
1316
|
+
footnote definitions are ignored. If more than one footnote definitions have the same footnote name,
|
|
1317
|
+
all footnote definitions but the last are ignored.
|
|
1238
1318
|
|
|
1239
1319
|
|
|
1240
1320
|
## Abbreviations
|
|
@@ -1266,7 +1346,7 @@ Here are some examples:
|
|
|
1266
1346
|
*[another language]: It's called Markdown
|
|
1267
1347
|
*[HTML]: HyperTextMarkupLanguage
|
|
1268
1348
|
|
|
1269
|
-
> Abbreviation definitions are, despite being described here, block level elements.
|
|
1349
|
+
> Abbreviation definitions are, despite being described here, non-content block level elements.
|
|
1270
1350
|
{: .information}
|
|
1271
1351
|
|
|
1272
1352
|
|
|
@@ -1285,16 +1365,24 @@ kramdown converts the following plain ASCII character into their corresponding t
|
|
|
1285
1365
|
* `>>` will become a right guillemet (like this >>) -- an optional leading space will become a
|
|
1286
1366
|
non-breakable space
|
|
1287
1367
|
|
|
1288
|
-
|
|
1289
|
-
when kramdown falsely replace the quotes. If this is the case, just \'escape\" the quotes and
|
|
1290
|
-
won't be replaced with fancy ones.
|
|
1368
|
+
The parser also replaces normal single `'` and double quotes `"` with "fancy quotes". There *may* be
|
|
1369
|
+
times when kramdown falsely replace the quotes. If this is the case, just \'escape\" the quotes and
|
|
1370
|
+
they won't be replaced with fancy ones.
|
|
1371
|
+
|
|
1291
1372
|
|
|
1292
1373
|
|
|
1374
|
+
# Non-content elements
|
|
1293
1375
|
|
|
1294
|
-
|
|
1376
|
+
This section describes the non-content elements that are used in kramdown documents, i.e. elements
|
|
1377
|
+
that don't provide content for the document but have other uses such as separating block level
|
|
1378
|
+
elements or attaching attributes to elements.
|
|
1295
1379
|
|
|
1296
|
-
|
|
1297
|
-
|
|
1380
|
+
Three non-content block level elements are not described here because they fit better where they
|
|
1381
|
+
are:
|
|
1382
|
+
|
|
1383
|
+
* [link definitions](#link-definitions)
|
|
1384
|
+
* [footnote definitions](#footnotes)
|
|
1385
|
+
* [abbreviation definition](#abbreviations)
|
|
1298
1386
|
|
|
1299
1387
|
|
|
1300
1388
|
## End-Of-Block Marker {#eob-marker}
|
|
@@ -1332,10 +1420,9 @@ By using an EOB marker, you can make two lists with one item each:
|
|
|
1332
1420
|
|
|
1333
1421
|
This is an implementation of [Maruku]'s feature for adding attributes to block and span level
|
|
1334
1422
|
elements (the naming is also taken from Maruku). This block level element is used to define
|
|
1335
|
-
attributes which can be referenced later. The [Block Inline Attribute
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
level element.
|
|
1423
|
+
attributes which can be referenced later. The [Block Inline Attribute List](#block-ials) is used to
|
|
1424
|
+
attach attributes to a block level element and the [Span Inline Attribute List](#span-ials) is used
|
|
1425
|
+
to attach attributes to a span level element.
|
|
1339
1426
|
|
|
1340
1427
|
Following are some examples of attribute list definitions (ALDs) and afterwards comes the syntax
|
|
1341
1428
|
explanation:
|
|
@@ -1352,45 +1439,46 @@ An ALD line has the following structure:
|
|
|
1352
1439
|
character except a not escaped closing brace),
|
|
1353
1440
|
* followed by a closing brace and optional spaces until the end of the line.
|
|
1354
1441
|
|
|
1355
|
-
The reference name needs to start with a word character or a digit, optionally followed by other
|
|
1356
|
-
characters, digits or dashes.
|
|
1442
|
+
The reference name needs to start with a word character or a digit, optionally followed by other
|
|
1443
|
+
word characters, digits or dashes.
|
|
1357
1444
|
|
|
1358
1445
|
There are four different types of attribute definitions which have to be separated by one or more
|
|
1359
1446
|
spaces:
|
|
1360
1447
|
|
|
1361
1448
|
references
|
|
1362
1449
|
|
|
1363
|
-
:
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
1450
|
+
: This must be a valid reference name. It is used to reference an other ALD so that the attributes
|
|
1451
|
+
of the other ALD are also included in this one. The reference name is ignored when collecting the
|
|
1452
|
+
attributes if no attribute definition list with this reference name exists. For example, a simple
|
|
1453
|
+
reference looks like `id`.
|
|
1367
1454
|
|
|
1368
1455
|
key-value pairs
|
|
1369
1456
|
|
|
1370
|
-
:
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1457
|
+
: A key-value pair is defined by a key name, which must follow the rules for reference names, then
|
|
1458
|
+
an equal sign and then the value in single or double quotes. If you need to use the value
|
|
1459
|
+
delimiter (a single or a double quote) inside the value, you need to escape it with a backslash.
|
|
1460
|
+
Key-value pairs can be used to specify arbitrary attributes for block or span level elements. For
|
|
1461
|
+
example, a key-value pair looks like `key1="bef \"quoted\" aft"` or `title='This is a title'`.
|
|
1375
1462
|
|
|
1376
1463
|
ID name
|
|
1377
1464
|
|
|
1378
|
-
:
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
1465
|
+
: An ID name is defined by using a hash and then the identifier name which needs to start with a
|
|
1466
|
+
word character or a digit, optionally followed by other word characters, digits, dashes or colons.
|
|
1467
|
+
This is a short hand for the key-value pair `id="IDNAME"` since this is often used. The ID name
|
|
1468
|
+
specifies the unique ID of a block or span level element. For example, an ID name looks like
|
|
1469
|
+
`#myid`.
|
|
1382
1470
|
|
|
1383
1471
|
class names
|
|
1384
1472
|
|
|
1385
|
-
:
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1473
|
+
: A class name is defined by using a dot and then the class name. This is (almost, but not quite) a
|
|
1474
|
+
short hand for the key-value pair `class="class-name"`. Almost because it actually means that the
|
|
1475
|
+
class name should be appended to the current value of the `class` attribute. The following ALDs
|
|
1476
|
+
are all equivalent:
|
|
1389
1477
|
|
|
1390
|
-
|
|
1391
|
-
|
|
1392
|
-
|
|
1393
|
-
|
|
1478
|
+
{:id: .cls1 .cls2}
|
|
1479
|
+
{:id: class="cls1" .cls2}
|
|
1480
|
+
{:id: class="something" class="cls1" .cls2}
|
|
1481
|
+
{:id: class="cls1 cls2}
|
|
1394
1482
|
|
|
1395
1483
|
As can be seen from the example of the class names, attributes that are defined earlier are
|
|
1396
1484
|
overwritten by ones with the same name defined later. Also, everything in the attribute definitions
|
|
@@ -1404,7 +1492,7 @@ ALDs are processed like they are defined in one ALD.
|
|
|
1404
1492
|
|
|
1405
1493
|
These elements are used to attach attributes to another element.
|
|
1406
1494
|
|
|
1407
|
-
### Block Inline Attribute Lists
|
|
1495
|
+
### Block Inline Attribute Lists {#block-ials}
|
|
1408
1496
|
|
|
1409
1497
|
> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
|
|
1410
1498
|
> the [Maruku] package.
|
|
@@ -1432,17 +1520,17 @@ Here are some examples for block IALs:
|
|
|
1432
1520
|
{:.ruby}
|
|
1433
1521
|
Some code here
|
|
1434
1522
|
|
|
1435
|
-
### Span Inline Attribute Lists
|
|
1523
|
+
### Span Inline Attribute Lists {#span-ials}
|
|
1436
1524
|
|
|
1437
1525
|
> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
|
|
1438
1526
|
> the [Maruku] package.
|
|
1439
1527
|
{: .markdown-difference}
|
|
1440
1528
|
|
|
1441
|
-
This is a version of the [block inline attribute list](#block-
|
|
1442
|
-
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
|
|
1529
|
+
This is a version of the [block inline attribute list](#block-ials) for span level elements. It has
|
|
1530
|
+
the same structure as the block IAL except that leading and trailing spaces are not allowed. A span
|
|
1531
|
+
IAL (or two or more span IALs) has to be put directly after the span level element to which it
|
|
1532
|
+
should be applied, no additional character is allowed between, otherwise it is ignored and only
|
|
1533
|
+
removed from the output.
|
|
1446
1534
|
|
|
1447
1535
|
Here are some examples for span IALs:
|
|
1448
1536
|
|
|
@@ -1473,7 +1561,7 @@ Here are some examples of how to specify extensions and afterwards is the syntax
|
|
|
1473
1561
|
An extension can be specified with or without a body. Therefore there exist a start and an end tag
|
|
1474
1562
|
for extensions. The start tag has the following structure:
|
|
1475
1563
|
|
|
1476
|
-
*
|
|
1564
|
+
* a left brace,
|
|
1477
1565
|
* followed by two colons and the extension name,
|
|
1478
1566
|
* optionally followed by a space and attribute definitions (allowed characters are backslash-escaped
|
|
1479
1567
|
closing braces or any character except a not escaped closing brace -- same as with ALDs),
|
|
@@ -1505,19 +1593,22 @@ The following extensions can be used with kramdown:
|
|
|
1505
1593
|
|
|
1506
1594
|
`comment`
|
|
1507
1595
|
|
|
1508
|
-
:
|
|
1596
|
+
: Treat the body text as a comment which does not show in the output.
|
|
1509
1597
|
|
|
1510
1598
|
`nomarkdown`
|
|
1511
1599
|
|
|
1512
|
-
:
|
|
1600
|
+
: Don't process the body with kramdown but output it as-is. The attribute `type` specifies which
|
|
1601
|
+
converters should output the body: if the attribute is missing, all converters should output it.
|
|
1602
|
+
Otherwise the attribute value has to be a space separated list of converter names and these
|
|
1603
|
+
converters should output the body.
|
|
1513
1604
|
|
|
1514
1605
|
`options`
|
|
1515
1606
|
|
|
1516
|
-
:
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
1520
|
-
|
|
1607
|
+
: Should be used without a body since the body is ignored. Is used for setting the global options
|
|
1608
|
+
for the kramdown processor (for example, to disable automatic header ID generation). Note that
|
|
1609
|
+
options that are used by the parser are immediately effective whereas all other options are not!
|
|
1610
|
+
This means, for example, that it is not possible to set converter options only for some part of a
|
|
1611
|
+
kramdown document.
|
|
1521
1612
|
|
|
1522
1613
|
|
|
1523
1614
|
|