kramdown 0.5.0 → 0.6.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/ChangeLog +315 -0
- data/Rakefile +35 -0
- data/VERSION +1 -1
- data/benchmark/generate_data.rb +6 -4
- data/benchmark/historic-jruby-1.4.0.dat +7 -7
- data/benchmark/historic-ruby-1.8.6.dat +7 -7
- data/benchmark/historic-ruby-1.8.7.dat +7 -7
- data/benchmark/historic-ruby-1.9.1p243.dat +7 -7
- data/benchmark/historic-ruby-1.9.2dev.dat +7 -7
- data/bin/kramdown +15 -4
- data/data/kramdown/document.html +9 -0
- data/data/kramdown/document.latex +38 -0
- data/doc/default.less.css +468 -0
- data/doc/default.template +23 -34
- data/doc/index.page +25 -20
- data/doc/news.page +1 -1
- data/doc/syntax.page +226 -159
- data/doc/tests.page +2 -1
- data/lib/kramdown/converter/html.rb +14 -2
- data/lib/kramdown/converter/latex.rb +19 -1
- data/lib/kramdown/document.rb +17 -9
- data/lib/kramdown/parser/kramdown.rb +4 -3
- data/lib/kramdown/parser/kramdown/autolink.rb +7 -2
- data/lib/kramdown/parser/kramdown/emphasis.rb +3 -2
- data/lib/kramdown/parser/kramdown/escaped_chars.rb +1 -1
- data/lib/kramdown/parser/kramdown/list.rb +2 -1
- data/lib/kramdown/parser/kramdown/math.rb +53 -0
- data/lib/kramdown/version.rb +1 -1
- data/man/man1/kramdown.1 +189 -0
- data/test/testcases/block/08_list/mixed.html +9 -3
- data/test/testcases/block/08_list/special_cases.html +49 -0
- data/test/testcases/block/08_list/special_cases.text +29 -0
- data/test/testcases/block/15_math/normal.html +19 -0
- data/test/testcases/block/15_math/normal.text +18 -0
- data/test/testcases/span/02_emphasis/errors.html +1 -1
- data/test/testcases/span/02_emphasis/nesting.html +4 -0
- data/test/testcases/span/02_emphasis/nesting.text +3 -0
- data/test/testcases/span/autolinks/url_links.html +3 -0
- data/test/testcases/span/autolinks/url_links.text +3 -0
- data/test/testcases/span/math/normal.html +5 -0
- data/test/testcases/span/math/normal.text +5 -0
- metadata +21 -6
- data/doc/default.css +0 -293
data/doc/default.template
CHANGED
|
@@ -8,53 +8,42 @@
|
|
|
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
|
-
|
|
11
|
+
<script src="{relocatable: js/jsMath/easy/load.js}" type="text/javascript"></script>
|
|
12
12
|
<title>{title:} | kramdown</title>
|
|
13
13
|
</head>
|
|
14
14
|
<body>
|
|
15
|
-
<div id="
|
|
16
|
-
|
|
15
|
+
<div id="fullheader">
|
|
17
16
|
<div id="header">
|
|
18
|
-
|
|
19
17
|
<h1 id="logo"><a href="{relocatable: /}" title="Homepage">kramdown <span class='slogan'>fast, pure-Ruby Markdown-superset converter</span></a></h1>
|
|
20
|
-
<hr class="noscreen" />
|
|
21
|
-
|
|
22
18
|
</div>
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
<div id="nav" class="box">
|
|
19
|
+
</div>
|
|
20
|
+
<div id="fullnav">
|
|
21
|
+
<div id="nav">
|
|
27
22
|
{menu: {max_levels: 1, used_nodes: files}}
|
|
28
|
-
<hr class="noscreen" />
|
|
29
23
|
</div>
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
<div id="intro">
|
|
35
|
-
<
|
|
36
|
-
<webgen:block name="intro" node="first" />
|
|
37
|
-
</div>
|
|
24
|
+
</div>
|
|
25
|
+
<div id="fullintro">
|
|
26
|
+
<% if context.content_node.node_info[:page].blocks.has_key?('intro') %>
|
|
27
|
+
<div id="intro">
|
|
28
|
+
<div id="intro-in">
|
|
29
|
+
<webgen:block name="intro" node="first" />
|
|
38
30
|
</div>
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
<div class="in">
|
|
43
|
-
<div class="shadow">
|
|
44
|
-
<webgen:block name="content" />
|
|
45
|
-
</div>
|
|
31
|
+
</div>
|
|
32
|
+
<% end %>
|
|
33
|
+
</div>
|
|
46
34
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
</div>
|
|
50
|
-
</div>
|
|
35
|
+
<div id="container">
|
|
51
36
|
|
|
37
|
+
<div id="main">
|
|
38
|
+
<webgen:block name="content" />
|
|
39
|
+
<div class="clear"></div>
|
|
52
40
|
</div>
|
|
53
41
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
</div>
|
|
42
|
+
</div>
|
|
43
|
+
|
|
44
|
+
<div id="footer" class="shadow">
|
|
45
|
+
<div class="float-left">Copyright © 2009 Thomas Leitner</div>
|
|
46
|
+
<div class="float-right">Based on a design by <a href="http://www.davidkohout.cz" title="Original template design">David Kohout</a></div>
|
|
58
47
|
</div>
|
|
59
48
|
|
|
60
49
|
<!-- Start of StatCounter Code -->
|
data/doc/index.page
CHANGED
|
@@ -3,17 +3,14 @@ title: Home
|
|
|
3
3
|
in_menu: true
|
|
4
4
|
sort_info: 1
|
|
5
5
|
---
|
|
6
|
-
##
|
|
6
|
+
## Overview
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
additional syntax. kramdown supports all features of the original Markdown syntax (albeit with some
|
|
12
|
-
minor corrections) as well as newer features implemented in the [PHP Markdown Extra] package and
|
|
13
|
-
[Maruku].
|
|
8
|
+
kramdown is first and foremost a library for converting text written in a superset of Markdown to
|
|
9
|
+
HTML. However, due to its modular architecture it is able to support additional input and output
|
|
10
|
+
formats. The following input and output formats are currently supported:
|
|
14
11
|
|
|
15
|
-
|
|
16
|
-
|
|
12
|
+
* Input: [kramdown](parser/kramdown.html) (a superset of Markdown)
|
|
13
|
+
* Output: [HTML](converter/html.html), [LaTeX](converter/latex.html)
|
|
17
14
|
|
|
18
15
|
|
|
19
16
|
## Usage
|
|
@@ -30,21 +27,22 @@ The kramdown package provides two ways for using it:
|
|
|
30
27
|
{: lang='ruby'}
|
|
31
28
|
|
|
32
29
|
The second parameter to the `new` call is an options hash for (de)activating certain features. For
|
|
33
|
-
more information have a look at the [API documentation](
|
|
30
|
+
more information have a look at the [API documentation](rdoc/index.html).
|
|
34
31
|
|
|
35
32
|
* **As an application**
|
|
36
33
|
|
|
37
34
|
Together with the library files a binary called `kramdown` is shipped which can be used to convert
|
|
38
|
-
text in
|
|
39
|
-
|
|
35
|
+
text in any supported format (currently only kramdown syntax) to any supported output format (e.g.
|
|
36
|
+
HTML or LaTeX). It either reads from the files specified as the command line arguments or from the
|
|
37
|
+
standard input. For example:
|
|
40
38
|
|
|
41
39
|
kramdown path/to/kramdown/doc/syntax.page
|
|
42
40
|
|
|
43
41
|
|
|
44
42
|
## Tests
|
|
45
43
|
|
|
46
|
-
kramdown uses various test suites to verify the correct working of the
|
|
47
|
-
|
|
44
|
+
kramdown uses various test suites to verify the correct working of the parsers and converters. For
|
|
45
|
+
more information, have a look at the [tests document](tests.html).
|
|
48
46
|
|
|
49
47
|
|
|
50
48
|
## Bugs, Forums, Mailing Lists
|
|
@@ -57,6 +55,13 @@ and [mailing lists][ml] available if you have any questions!
|
|
|
57
55
|
[ml]: http://rubyforge.org/mail/?group_id=7403
|
|
58
56
|
|
|
59
57
|
|
|
58
|
+
## Thanks
|
|
59
|
+
|
|
60
|
+
kramdown would not be possible without the prior work of many other people. I want to thank everyone
|
|
61
|
+
involved with making Markdown such a nice markup language and especially the developers of other
|
|
62
|
+
Markdown implementations because kramdown borrowed many ideas from existing packages.
|
|
63
|
+
|
|
64
|
+
|
|
60
65
|
## Author
|
|
61
66
|
|
|
62
67
|
* Thomas Leitner
|
|
@@ -75,16 +80,16 @@ and [mailing lists][ml] available if you have any questions!
|
|
|
75
80
|
## Welcome to the kramdown site
|
|
76
81
|
|
|
77
82
|
**kramdown** (sic, not Kramdown or KramDown, just kramdown) is a *free* GPL-licensed
|
|
78
|
-
[Ruby](http://www.ruby-lang.org) library for parsing a superset of Markdown. It is
|
|
79
|
-
written in Ruby, supports standard Markdown (with some minor modifications) and various
|
|
80
|
-
that have been made popular by the [PHP Markdown Extra] package and [Maruku].
|
|
83
|
+
[Ruby](http://www.ruby-lang.org) library for parsing and converting a superset of Markdown. It is
|
|
84
|
+
completely written in Ruby, supports standard Markdown (with some minor modifications) and various
|
|
85
|
+
extensions that have been made popular by the [PHP Markdown Extra] package and [Maruku].
|
|
81
86
|
|
|
82
87
|
It is probably the fastest pure-Ruby Markdown converter available (February 2010), being about 4.5x
|
|
83
88
|
faster than [Maruku] and about 10x faster than [BlueFeather].
|
|
84
89
|
|
|
85
|
-
<
|
|
86
|
-
The latest version of kramdown is <b>0.
|
|
87
|
-
</
|
|
90
|
+
<p class="a-center">
|
|
91
|
+
The latest version of kramdown is <b>0.6.0</b> and it was released on <b>2010-04-06</b>.
|
|
92
|
+
</p>
|
|
88
93
|
|
|
89
94
|
[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
|
|
90
95
|
[Maruku]: http://maruku.rubyforge.org
|
data/doc/news.page
CHANGED
|
@@ -18,7 +18,7 @@ end.collect {|na,no| no}.sort.reverse.each do |node|
|
|
|
18
18
|
%>
|
|
19
19
|
|
|
20
20
|
<div class='news-item'>
|
|
21
|
-
<div class="news-date
|
|
21
|
+
<div class="news-date float-right">
|
|
22
22
|
Published on <%= node['created_at'].strftime("%A, %d %B %Y") %>
|
|
23
23
|
</div>
|
|
24
24
|
<%= context.render_block(:name => 'content', :chain => [node]) %>
|
data/doc/syntax.page
CHANGED
|
@@ -18,43 +18,44 @@ with Markdown. Nonetheless, most Markdown documents should work fine when parsed
|
|
|
18
18
|
places where the kramdown syntax differs from the Markdown syntax are highlighted.
|
|
19
19
|
|
|
20
20
|
Following is the complete syntax definition so that you know what you will get when a kramdown
|
|
21
|
-
document is converted to HTML.
|
|
22
|
-
(paragraphs, blockquotes, ...) and span level elements (emphasis, links, ...). Each has its own
|
|
23
|
-
section.
|
|
21
|
+
document is converted to, for example, HTML.
|
|
24
22
|
|
|
25
23
|
[Maruku]: http://maruku.rubyforge.org
|
|
26
24
|
[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
|
|
27
25
|
[Pandoc]: http://johnmacfarlane.net/pandoc/
|
|
28
26
|
|
|
29
27
|
|
|
30
|
-
##
|
|
28
|
+
## Source Text Formatting
|
|
31
29
|
|
|
32
|
-
kramdown
|
|
33
|
-
|
|
34
|
-
|
|
30
|
+
A kramdown document may be in any encoding, for example ASCII, UTF-8 or ISO-8859-1, and the output
|
|
31
|
+
will have the same encoding as the source. It consists of two types of elements, block level
|
|
32
|
+
elements and span level elements:
|
|
35
33
|
|
|
34
|
+
* Block level elements define the main structure of the content, for example, what part of the text
|
|
35
|
+
should be a paragraph, a list, a blockquote and so on.
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
* Span level elements mark up small text parts as, for example, emphasized text or a link.
|
|
38
38
|
|
|
39
|
-
|
|
40
|
-
characters are used inside a code block or code span, they are always automatically escaped to their
|
|
41
|
-
HTML entity counterparts.
|
|
39
|
+
Thus span level elements can only occur inside block level elements or other span level elements.
|
|
42
40
|
|
|
43
|
-
When used inside the normal text flow:
|
|
44
41
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
42
|
+
### Usage of Tabs
|
|
43
|
+
|
|
44
|
+
kramdown assumes that tab stops are set at multiples of four. This is especially important when
|
|
45
|
+
using tabs for indentation in lists. Also, tabs may only be used at the beginning of a line when
|
|
46
|
+
indenting text and must not be preceded by spaces. Otherwise the results may be unexpected.
|
|
48
47
|
|
|
49
|
-
For example, the following fragment:
|
|
50
48
|
|
|
51
|
-
|
|
52
|
-
0 < 1 < 2 and 2 > 1 > 0
|
|
49
|
+
### Automatic and Manual Escaping
|
|
53
50
|
|
|
54
|
-
|
|
51
|
+
Depending on the output format, there are often characters that need special treatment. For example,
|
|
52
|
+
when converting a kramdown document to HTML one needs to take care of the characters `<`, `>` and
|
|
53
|
+
`&`. To ease working with these special characters, they are automatically and correctly escaped
|
|
54
|
+
depending on the output format.
|
|
55
55
|
|
|
56
|
-
|
|
57
|
-
|
|
56
|
+
This means, for example, that you can just use `<`, `>` and `&` in a kramdown document and need not
|
|
57
|
+
think about when to use their HTML entity counterparts. However, if you *do use* HTML entitys or
|
|
58
|
+
HTML tags which use one of the characters, the result will be correct nonetheless!
|
|
58
59
|
|
|
59
60
|
Since kramdown also uses some characters to mark-up the text, there need to be a way to escape these
|
|
60
61
|
special characters so that they can have their normal meaning. This can be done by using backslash
|
|
@@ -62,7 +63,7 @@ escapes. For example, you can use a literal backtick like this:
|
|
|
62
63
|
|
|
63
64
|
This \`is not a code\` span!
|
|
64
65
|
|
|
65
|
-
Following is a list of all
|
|
66
|
+
Following is a list of all the characters (character sequences) that can be escaped:
|
|
66
67
|
|
|
67
68
|
\ backslash
|
|
68
69
|
. period
|
|
@@ -71,7 +72,7 @@ Following is a list of all those characters (character sequences) that can be es
|
|
|
71
72
|
+ plus
|
|
72
73
|
- minus
|
|
73
74
|
` backtick
|
|
74
|
-
()[]{} parens/brackets/braces
|
|
75
|
+
()[]{} left and right parens/brackets/braces
|
|
75
76
|
# hash
|
|
76
77
|
! bang
|
|
77
78
|
<< left guillemet
|
|
@@ -80,32 +81,13 @@ Following is a list of all those characters (character sequences) that can be es
|
|
|
80
81
|
| pipe
|
|
81
82
|
" double quote
|
|
82
83
|
' single quote
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
## Typographic Symbols
|
|
86
|
-
|
|
87
|
-
kramdown converts the following plain ASCII character into their corresponding typographic symbols:
|
|
88
|
-
|
|
89
|
-
* `---` will become an em-dash (like this ---)
|
|
90
|
-
* `--` will become an en-dash (like this --)
|
|
91
|
-
* `...` will become an ellipsis (like this ...)
|
|
92
|
-
* `<<` will become a left guillemet (like this <<) -- an optional following space will become a
|
|
93
|
-
non-breakable space
|
|
94
|
-
* `>>` will become a right guillemet (like this >>) -- an optional leading space will become a
|
|
95
|
-
non-breakable space
|
|
96
|
-
|
|
97
|
-
It also replaces normal single `'` and double quotes `"` with "fancy quotes". There *may* be times
|
|
98
|
-
when kramdown falsely replace the quotes. If this is the case, just \'escape\" the quotes and they
|
|
99
|
-
won't be replaced with fancy ones.
|
|
100
|
-
|
|
101
|
-
> The original Markdown program does not do this transformations.
|
|
102
|
-
{: .markdown-difference}
|
|
84
|
+
$ dollar sign
|
|
103
85
|
|
|
104
86
|
|
|
105
87
|
# Block Level Elements
|
|
106
88
|
|
|
107
|
-
Block level elements are used to structure the content. They can mark up some text, for example,
|
|
108
|
-
|
|
89
|
+
Block level elements are used to structure the content. They can mark up some text as, for example,
|
|
90
|
+
a simple paragraph, a quote or as a list item.
|
|
109
91
|
|
|
110
92
|
You will often find references to the "first column" or "first character" of a line in the block
|
|
111
93
|
level element descriptions. Such a reference is always to be taken relative to the current
|
|
@@ -127,14 +109,19 @@ meaning:
|
|
|
127
109
|
* When used in lists -- see the [lists section](#lists)
|
|
128
110
|
|
|
129
111
|
|
|
130
|
-
## End-Of-Block Marker
|
|
112
|
+
## End-Of-Block Marker {#eob-marker}
|
|
113
|
+
|
|
114
|
+
> The EOB marker is not part of the standard Markdown syntax.
|
|
115
|
+
{: .markdown-difference}
|
|
131
116
|
|
|
132
117
|
The End-Of-Block (EOB) marker -- a `^` as first character on an otherwise empty line -- can be used
|
|
133
118
|
to specify the end of a block level element even if the block level element, after which it is used,
|
|
134
|
-
would continue otherwise. If there is no block to end, the EOB marker is simply
|
|
119
|
+
would continue otherwise. If there is no block level element to end, the EOB marker is simply
|
|
120
|
+
ignored.
|
|
135
121
|
|
|
136
122
|
You won't find an EOB marker in most kramdown documents but sometimes it is necessary to use it to
|
|
137
|
-
achieve the wanted results which would be impossible otherwise.
|
|
123
|
+
achieve the wanted results which would be impossible otherwise. However, it should only be used when
|
|
124
|
+
absolutely necesary!
|
|
138
125
|
|
|
139
126
|
For example, the following gives you one list with two items:
|
|
140
127
|
|
|
@@ -142,22 +129,19 @@ For example, the following gives you one list with two items:
|
|
|
142
129
|
|
|
143
130
|
* list item two
|
|
144
131
|
|
|
145
|
-
By using an EOB marker, you can make two lists with
|
|
132
|
+
By using an EOB marker, you can make two lists with one item each:
|
|
146
133
|
|
|
147
134
|
* list one
|
|
148
135
|
^
|
|
149
136
|
* list two
|
|
150
137
|
|
|
151
|
-
> The EOB marker is not part of the standard Markdown syntax.
|
|
152
|
-
{: .markdown-difference}
|
|
153
|
-
|
|
154
138
|
|
|
155
139
|
## Paragraphs
|
|
156
140
|
|
|
157
141
|
Paragraphs are the most used block level elements. One or more consecutive lines of text are
|
|
158
142
|
interpreted as one paragraph. Every line of a paragraph may be indented up to three spaces. You can
|
|
159
143
|
separate two consecutive paragraphs from each other by using one or more blank lines. Notice that a
|
|
160
|
-
line break in the source does not mean a line break in the output
|
|
144
|
+
line break in the source does not mean a line break in the output! If you want to have an explicit
|
|
161
145
|
line break (i.e. a `<br />` tag) you need to end a line with two or more spaces or two backslashes!
|
|
162
146
|
Note, however, that a line break on the last text line of a paragraph is not possible and will be
|
|
163
147
|
ignored. Leading and trailing spaces will be stripped from the paragraph text.
|
|
@@ -170,22 +154,22 @@ The following gives you an example of how paragraphs look like:
|
|
|
170
154
|
|
|
171
155
|
This is another paragraph, not connected to the above one. But
|
|
172
156
|
with a hard line break. \\
|
|
173
|
-
|
|
157
|
+
And another one.
|
|
174
158
|
{: .show-whitespaces .ws-lr}
|
|
175
159
|
|
|
176
160
|
|
|
177
161
|
## Headers
|
|
178
162
|
|
|
179
|
-
kramdown supports Setext style and atx style headers.
|
|
163
|
+
kramdown supports so called Setext style and atx style headers.
|
|
180
164
|
|
|
181
165
|
### Setext Style
|
|
182
166
|
|
|
183
|
-
Setext style headers are specified by a blank line (except at the beginning of a
|
|
184
|
-
of text (the header text)
|
|
185
|
-
dashes (for a second level header). The header text may be indented up to
|
|
186
|
-
or trailing spaces are stripped from the header text. The amount of
|
|
187
|
-
significant, just one is enough but more may look better. The equal
|
|
188
|
-
the first column. For example:
|
|
167
|
+
Setext style headers are specified by a [blank line](#blank-lines) (except at the beginning of a
|
|
168
|
+
document), followed by a line of text (the header text) and a line with only equal signs (for a
|
|
169
|
+
first level header) or dashes (for a second level header). The header text may be indented up to
|
|
170
|
+
three spaces but any leading or trailing spaces are stripped from the header text. The amount of
|
|
171
|
+
equal signs or dashes is not significant, just one is enough but more may look better. The equal
|
|
172
|
+
signs or dashes have to begin at the first column. For example:
|
|
189
173
|
|
|
190
174
|
First level header
|
|
191
175
|
==================
|
|
@@ -196,7 +180,7 @@ the first column. For example:
|
|
|
196
180
|
Other first level header
|
|
197
181
|
=
|
|
198
182
|
|
|
199
|
-
As mentioned you need to insert a blank line before a Setext header:
|
|
183
|
+
As mentioned you need to insert a blank line before (but not necessarily after) a Setext header:
|
|
200
184
|
|
|
201
185
|
This is a normal
|
|
202
186
|
paragraph.
|
|
@@ -214,8 +198,8 @@ However, it is generally a good idea to also use a blank line after a Setext hea
|
|
|
214
198
|
more appropriate.
|
|
215
199
|
|
|
216
200
|
> The original Markdown syntax allows one to omit the blank line before a Setext header. However,
|
|
217
|
-
> this makes reading the document harder than necessary
|
|
218
|
-
> document.
|
|
201
|
+
> this leads to ambiguities and makes reading the document harder than necessary. Therefore it is
|
|
202
|
+
> not allowed in a kramdown document.
|
|
219
203
|
{: .markdown-difference}
|
|
220
204
|
|
|
221
205
|
An edge case worth mentioning is the following:
|
|
@@ -224,18 +208,19 @@ An edge case worth mentioning is the following:
|
|
|
224
208
|
---
|
|
225
209
|
para
|
|
226
210
|
|
|
227
|
-
One might ask if this represents two paragraphs separated by a horizontal
|
|
228
|
-
header and a paragraph. As suggested by the wording in the example, the latter is
|
|
229
|
-
general rule is that Setext headers are processed before horizontal rules.
|
|
211
|
+
One might ask if this represents two paragraphs separated by a [horizontal rule](#horizontal-rules)
|
|
212
|
+
or a second level header and a paragraph. As suggested by the wording in the example, the latter is
|
|
213
|
+
the case. The general rule is that Setext headers are processed before horizontal rules.
|
|
230
214
|
|
|
231
215
|
### atx Style
|
|
232
216
|
|
|
233
|
-
atx style headers
|
|
234
|
-
with one or more hash characters and then the header text. No spaces
|
|
235
|
-
characters. The number of hash characters specifies the heading level:
|
|
236
|
-
a first level heading, two a second level heading and so on
|
|
237
|
-
for a sixth level heading. You may optionally use any number of
|
|
238
|
-
close the header. Any leading or trailing spaces are stripped from
|
|
217
|
+
atx style headers are specified by a [blank line](#blank-lines) (except at the beginning of a
|
|
218
|
+
document), followed by a line with one or more hash characters and then the header text. No spaces
|
|
219
|
+
are allowed before the hash characters. The number of hash characters specifies the heading level:
|
|
220
|
+
one hash character gives you a first level heading, two a second level heading and so on until the
|
|
221
|
+
maximum of six hash characters for a sixth level heading. You may optionally use any number of
|
|
222
|
+
hashes at the end of the line to close the header. Any leading or trailing spaces are stripped from
|
|
223
|
+
the header text. For example:
|
|
239
224
|
|
|
240
225
|
# First level header
|
|
241
226
|
|
|
@@ -248,12 +233,12 @@ close the header. Any leading or trailing spaces are stripped from the header te
|
|
|
248
233
|
|
|
249
234
|
### Automatic Generation of Header IDs
|
|
250
235
|
|
|
251
|
-
kramdown supports the automatic generation of header IDs if the option
|
|
236
|
+
kramdown supports the automatic generation of header IDs if the option `auto_ids` is set to `true`
|
|
252
237
|
(which is the default). This is done by converting the untransformed, i.e. plain, header text via the
|
|
253
238
|
following steps:
|
|
254
239
|
|
|
255
240
|
* All characters except letters, numbers, spaces and dashes are removed.
|
|
256
|
-
* All characters from the start of the line
|
|
241
|
+
* All characters from the start of the line until the first letter are removed.
|
|
257
242
|
* Everything except letters and numbers is converted to dashes.
|
|
258
243
|
* Everything is lowercased.
|
|
259
244
|
* If nothing is left, the identifier `section` is used.
|
|
@@ -291,11 +276,11 @@ Following are some examples of header texts and their respective generated IDs:
|
|
|
291
276
|
|
|
292
277
|
### Manually Specifying a Header ID
|
|
293
278
|
|
|
294
|
-
Additionally, kramdown supports a nice way for setting
|
|
295
|
-
Markdown Extra] and [Maruku]: If you follow the header text
|
|
296
|
-
from the text with a least one space), a hash, the ID and a
|
|
297
|
-
the header. If you use the trailing hash feature of atx
|
|
298
|
-
the trailing hashes. For example:
|
|
279
|
+
Additionally to automatic header ID generation, kramdown supports a nice way for explicitly setting
|
|
280
|
+
the header ID which is taken from [PHP Markdown Extra] and [Maruku]: If you follow the header text
|
|
281
|
+
with an opening curly bracket (separated from the text with a least one space), a hash, the ID and a
|
|
282
|
+
closing curly bracket, the ID is set on the header. If you use the trailing hash feature of atx
|
|
283
|
+
style headers, the header ID has to go after the trailing hashes. For example:
|
|
299
284
|
|
|
300
285
|
Hello {#id}
|
|
301
286
|
-----
|
|
@@ -310,11 +295,11 @@ the trailing hashes. For example:
|
|
|
310
295
|
|
|
311
296
|
## Blockquotes
|
|
312
297
|
|
|
313
|
-
A blockquote is started using the `>` marker followed by an optional space
|
|
314
|
-
indented up to three spaces. All following lines that are also
|
|
315
|
-
belong to the blockquote. The contents of a blockquote are block
|
|
316
|
-
you are just using text as content that it will be wrapped in a
|
|
317
|
-
following gives you one blockquote with two paragraphs in it:
|
|
298
|
+
A blockquote is started using the `>` marker followed by an optional space and the content of the
|
|
299
|
+
blockquote. The marker itself may be indented up to three spaces. All following lines that are also
|
|
300
|
+
started with the blockquote marker belong to the blockquote. The contents of a blockquote are block
|
|
301
|
+
level elements. This means that if you are just using text as content that it will be wrapped in a
|
|
302
|
+
paragraph. For example, the following gives you one blockquote with two paragraphs in it:
|
|
318
303
|
|
|
319
304
|
> This is a blockquote.
|
|
320
305
|
>on multiple lines.
|
|
@@ -334,8 +319,8 @@ block level elements:
|
|
|
334
319
|
> and all other block level elements
|
|
335
320
|
|
|
336
321
|
Note that the first space character after the `>` marker does *not* count when counting spaces for
|
|
337
|
-
the indentation of the block level elements inside the blockquote! So code blocks
|
|
338
|
-
indented with five spaces or one space and one tab, like this:
|
|
322
|
+
the indentation of the block level elements inside the blockquote! So [code blocks](#code-blocks)
|
|
323
|
+
will have to be indented with five spaces or one space and one tab, like this:
|
|
339
324
|
|
|
340
325
|
> A code block:
|
|
341
326
|
>
|
|
@@ -356,9 +341,8 @@ indented with five spaces or one space and one tab, like this:
|
|
|
356
341
|
|
|
357
342
|
## Code Blocks
|
|
358
343
|
|
|
359
|
-
Code blocks can be used to represent verbatim text like markup, HTML or a program fragment
|
|
360
|
-
syntax is parsed within a code block
|
|
361
|
-
counterparts. A code block is wrapped in both `<pre>` and `<code>` tags.
|
|
344
|
+
Code blocks can be used to represent verbatim text like markup, HTML or a program fragment because
|
|
345
|
+
no syntax is parsed within a code block.
|
|
362
346
|
|
|
363
347
|
### Standard Code Block
|
|
364
348
|
|
|
@@ -371,8 +355,8 @@ blocks:
|
|
|
371
355
|
|
|
372
356
|
This text belongs to the same code block.
|
|
373
357
|
|
|
374
|
-
If you want to have one code block directly after another one, you need to use an EOB
|
|
375
|
-
separate the two:
|
|
358
|
+
If you want to have one code block directly after another one, you need to use an [EOB
|
|
359
|
+
marker](#eob-marker) to separate the two:
|
|
376
360
|
|
|
377
361
|
Here comes some code
|
|
378
362
|
^
|
|
@@ -408,15 +392,11 @@ code.
|
|
|
408
392
|
|
|
409
393
|
### Showing Whitespace in a Code Block
|
|
410
394
|
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
395
|
+
It is sometimes useful to visualize whitespace within a code block. This can be achieved in kramdown
|
|
396
|
+
by adding the class `show-whitespaces` to a code block (using a [block
|
|
397
|
+
IAL](#block-inline-attribute-lists)).
|
|
414
398
|
|
|
415
|
-
|
|
416
|
-
* `ws-space-r`, `ws-tab-r`: trailing spaces/tabs
|
|
417
|
-
* `ws-space`, `ws-tab`: spaces/tabs in between
|
|
418
|
-
|
|
419
|
-
Here is an example output:
|
|
399
|
+
Here is an example where the whitespaces are shown:
|
|
420
400
|
|
|
421
401
|
leading tab and space
|
|
422
402
|
trailing tab and space
|
|
@@ -425,12 +405,11 @@ Here is an example output:
|
|
|
425
405
|
|
|
426
406
|
### Automatic Syntax Highlighting {#syntax-highlighting}
|
|
427
407
|
|
|
428
|
-
kramdown supports syntax highlighting of code
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
value has to be a language supported by CodeRay.
|
|
408
|
+
kramdown supports syntax highlighting of code. Just add the key `lang` to a code block (using a
|
|
409
|
+
[block IAL](#block-inline-attribute-lists)) and it will be highlighted using the specified language.
|
|
410
|
+
Details on the supported languages can be found in the documentation for each converter.
|
|
432
411
|
|
|
433
|
-
Here is an example
|
|
412
|
+
Here is an example on how Ruby code is highlighted:
|
|
434
413
|
|
|
435
414
|
require 'kramdown'
|
|
436
415
|
|
|
@@ -441,10 +420,10 @@ Here is an example output:
|
|
|
441
420
|
|
|
442
421
|
## Horizontal Rules
|
|
443
422
|
|
|
444
|
-
A horizontal rule is created by using three or more asterisks,
|
|
445
|
-
be mixed on
|
|
446
|
-
asterisk, dash or underscore may optionally be indented up to
|
|
447
|
-
show different possibilities to create a horizontal rule:
|
|
423
|
+
A horizontal rule for visually separating content is created by using three or more asterisks,
|
|
424
|
+
dashes or underscores (these may not be mixed on a line), optionally separated by spaces or tabs, on
|
|
425
|
+
an otherwise blank line. The first asterisk, dash or underscore may optionally be indented up to
|
|
426
|
+
three spaces. The following examples show different possibilities to create a horizontal rule:
|
|
448
427
|
|
|
449
428
|
* * *
|
|
450
429
|
|
|
@@ -515,7 +494,8 @@ different (marker and list content) indents for same level list items!
|
|
|
515
494
|
{: .markdown-difference}
|
|
516
495
|
|
|
517
496
|
When using tabs for indenting the content of a list item, remember that tab stops occur at multiples
|
|
518
|
-
of four. Tabs are converted to spaces for calculating the indentation. For
|
|
497
|
+
of four for kramdown. Tabs are correctly converted to spaces for calculating the indentation. For
|
|
498
|
+
example:
|
|
519
499
|
|
|
520
500
|
* Using a tab to indent this line, the tab only counts as three spaces and therefore the
|
|
521
501
|
overall indentation is four spaces.
|
|
@@ -524,8 +504,8 @@ of four. Tabs are converted to spaces for calculating the indentation. For examp
|
|
|
524
504
|
is three spaces and the marker itself takes two characters, the overall indentation
|
|
525
505
|
needed for the following lines is eight spaces or two tabs.
|
|
526
506
|
|
|
527
|
-
It is clear that you might get unexpected results if you mix tabs and spaces
|
|
528
|
-
stops set to multiples of four! Therefore this should be avoided!
|
|
507
|
+
It is clear that you might get unexpected results if you mix tabs and spaces or if you don't have
|
|
508
|
+
the tab stops set to multiples of four in your editor! Therefore this should be avoided!
|
|
529
509
|
|
|
530
510
|
The content of a list item is made up of either text or block level elements. Simple list items only
|
|
531
511
|
contain text like in the above examples. They are not even wrapped in a paragraph tag. If the first
|
|
@@ -549,6 +529,16 @@ by leaving a blank line after the last list item and using an EOB marker:
|
|
|
549
529
|
|
|
550
530
|
^
|
|
551
531
|
|
|
532
|
+
The text of the last list item is also wrapped in a paragraph tag if *all* other list items contain
|
|
533
|
+
a proper paragraph as first element. This makes the following use case work like expected, i.e.
|
|
534
|
+
*all* the list items are wrapped in paragraphs:
|
|
535
|
+
|
|
536
|
+
* First list item
|
|
537
|
+
|
|
538
|
+
* Second list item
|
|
539
|
+
|
|
540
|
+
* Last list item
|
|
541
|
+
|
|
552
542
|
> The original Markdown syntax page specifies that list items which are separated by one or more
|
|
553
543
|
> blank lines are wrapped in paragraph tags. This means that the first text will also be wrapped in
|
|
554
544
|
> a paragraph if you have block level elements in a list which are separated by blank lines. The
|
|
@@ -569,8 +559,8 @@ Since the content of a list item can contain block level elements, you can do th
|
|
|
569
559
|
|
|
570
560
|
* Second item
|
|
571
561
|
|
|
572
|
-
However, there is a problem when you want to
|
|
573
|
-
|
|
562
|
+
However, there is a problem when you want to have a code block immediately after a list item. You
|
|
563
|
+
can use an EOB marker to circumvent this problem:
|
|
574
564
|
|
|
575
565
|
* This is a list item.
|
|
576
566
|
|
|
@@ -716,7 +706,7 @@ There are three different text line types that can be used in a table:
|
|
|
716
706
|
text of the first table cell. Subsequent table cells consist of a pipe character followed by the
|
|
717
707
|
cell text. One may optionally use a pipe character at the the end of a table row line.
|
|
718
708
|
|
|
719
|
-
Header rows, footer rows and normal rows are all
|
|
709
|
+
Header rows, footer rows and normal rows are all done using these table rows. Table cells can only
|
|
720
710
|
contain a single line of text, no multiline text is supported. The text of a table cell is parsed
|
|
721
711
|
as span level elements. Note that literal pipe characters need to be escaped, even if they occur
|
|
722
712
|
in code spans!
|
|
@@ -830,6 +820,66 @@ editor. However, the table syntax is flexible and the above table could also be
|
|
|
830
820
|
| Footer row
|
|
831
821
|
|
|
832
822
|
|
|
823
|
+
## Math Blocks
|
|
824
|
+
|
|
825
|
+
> This syntax feature is not part of the original Markdown syntax. The idea comes from the [Maruku]
|
|
826
|
+
> and [Pandoc] packages.
|
|
827
|
+
{: .markdown-difference}
|
|
828
|
+
|
|
829
|
+
kramdown has built-in support for block and span level mathematics written in LaTeX.
|
|
830
|
+
|
|
831
|
+
A math block is started using two dollar signs, optionally indented up to three spaces. The math
|
|
832
|
+
block continues until the next two dollar signs (which may be on the same line or on one of the next
|
|
833
|
+
lines) that appear at the end of a line, i.e. they may only be followed by whitespace characters.
|
|
834
|
+
The content of a math block has to be valid LaTeX math. It is always wrapped inside a
|
|
835
|
+
`\begin{displaymath}...\end{displaymath}` enviroment except if it begins with a `\begin` statement.
|
|
836
|
+
|
|
837
|
+
The following kramdown fragment
|
|
838
|
+
|
|
839
|
+
$$
|
|
840
|
+
\begin{align*}
|
|
841
|
+
& \phi(x,y) = \phi \left(\sum_{i=1}^n x_ie_i, \sum_{j=1}^n y_je_j \right)
|
|
842
|
+
= \sum_{i=1}^n \sum_{j=1}^n x_i y_j \phi(e_i, e_j) = \\
|
|
843
|
+
& (x_1, \ldots, x_n) \left( \begin{array}{ccc}
|
|
844
|
+
\phi(e_1, e_1) & \cdots & \phi(e_1, e_n) \\
|
|
845
|
+
\vdots & \ddots & \vdots \\
|
|
846
|
+
\phi(e_n, e_1) & \cdots & \phi(e_n, e_n)
|
|
847
|
+
\end{array} \right)
|
|
848
|
+
\left( \begin{array}{c}
|
|
849
|
+
y_1 \\
|
|
850
|
+
\vdots \\
|
|
851
|
+
y_n
|
|
852
|
+
\end{array} \right)
|
|
853
|
+
\end{align*}
|
|
854
|
+
$$
|
|
855
|
+
|
|
856
|
+
renders as
|
|
857
|
+
|
|
858
|
+
$$
|
|
859
|
+
\begin{align*}
|
|
860
|
+
& \phi(x,y) = \phi \left(\sum_{i=1}^n x_ie_i, \sum_{j=1}^n y_je_j \right)
|
|
861
|
+
= \sum_{i=1}^n \sum_{j=1}^n x_i y_j \phi(e_i, e_j) = \\
|
|
862
|
+
& (x_1, \ldots, x_n) \left( \begin{array}{ccc}
|
|
863
|
+
\phi(e_1, e_1) & \cdots & \phi(e_1, e_n) \\
|
|
864
|
+
\vdots & \ddots & \vdots \\
|
|
865
|
+
\phi(e_n, e_1) & \cdots & \phi(e_n, e_n)
|
|
866
|
+
\end{array} \right)
|
|
867
|
+
\left( \begin{array}{c}
|
|
868
|
+
y_1 \\
|
|
869
|
+
\vdots \\
|
|
870
|
+
y_n
|
|
871
|
+
\end{array} \right)
|
|
872
|
+
\end{align*}
|
|
873
|
+
$$
|
|
874
|
+
|
|
875
|
+
Using inline math is also easy: just surround your math content with two dollar signs, like with a
|
|
876
|
+
math block.
|
|
877
|
+
|
|
878
|
+
If you don't want to start a math block or an inline math statement, just escape the dollar signs
|
|
879
|
+
and they will be treated as simple dollar signs. If you want to start an inline math statement at
|
|
880
|
+
the beginning of a paragraph, just escape the first dollar sign.
|
|
881
|
+
|
|
882
|
+
|
|
833
883
|
## HTML Blocks
|
|
834
884
|
|
|
835
885
|
> The original Markdown syntax specifies that an HTML block must start at the left margin, i.e. no
|
|
@@ -879,9 +929,9 @@ inside a raw HTML block.
|
|
|
879
929
|
Also, if an invalid closing tag is found, it is ignored.
|
|
880
930
|
|
|
881
931
|
By default, kramdown parses all block HTML tags and all XML tags as raw HTML blocks. However, this
|
|
882
|
-
can be configured with the
|
|
883
|
-
|
|
884
|
-
|
|
932
|
+
can be configured with the `parse_block_html`. If this is set to `true`, then syntax parsing in HTML
|
|
933
|
+
blocks is globally enabled. It is also possible to enable/disable syntax parsing on a tag per tag
|
|
934
|
+
basis using the `markdown` attribute:
|
|
885
935
|
|
|
886
936
|
* If an HTML tag has an attribute `markdown="0"`, then the tag is parsed as raw HTML block.
|
|
887
937
|
|
|
@@ -895,7 +945,7 @@ per tag basis using the `markdown` attribute:
|
|
|
895
945
|
level elements.
|
|
896
946
|
|
|
897
947
|
The following list shows which HTML tags are parsed in which mode by default when `markdown="1"` is
|
|
898
|
-
applied or
|
|
948
|
+
applied or `parse_block_html` is `true`:
|
|
899
949
|
|
|
900
950
|
Parse as raw HTML block
|
|
901
951
|
:
|
|
@@ -918,7 +968,7 @@ Parse as span level elements
|
|
|
918
968
|
> above lists also include span level HTML tags in the case the `markdown` attribute is used on a
|
|
919
969
|
> tag inside a raw HTML block.
|
|
920
970
|
|
|
921
|
-
Here is a simple example input and its output with
|
|
971
|
+
Here is a simple example input and its HTML output with `parse_block_html` set to `false`:
|
|
922
972
|
|
|
923
973
|
This is a para.
|
|
924
974
|
<div>
|
|
@@ -957,7 +1007,7 @@ appears after a start/end tag but on the same line, is processed as if it appear
|
|
|
957
1007
|
<div markdown="1">The end tag is not found because
|
|
958
1008
|
this line is parsed as a paragraph</div>
|
|
959
1009
|
|
|
960
|
-
Since setting
|
|
1010
|
+
Since setting `parse_block_html` to `true` can lead to some not wanted behaviour, it is generally
|
|
961
1011
|
better to selectively enable or disable block/span level elements parsing by using the `markdown`
|
|
962
1012
|
attribute!
|
|
963
1013
|
|
|
@@ -1014,7 +1064,7 @@ An ALD line has the following structure:
|
|
|
1014
1064
|
* followed by a colon, the reference name and another colon,
|
|
1015
1065
|
* followed by attribute definitions (allowed characters are backslash-escaped closing braces or any
|
|
1016
1066
|
character except a not escaped closing brace),
|
|
1017
|
-
* followed by a closing brace and optional spaces
|
|
1067
|
+
* followed by a closing brace and optional spaces until the end of the line.
|
|
1018
1068
|
|
|
1019
1069
|
The reference name needs to start with a word character or a digit, optionally followed by other word
|
|
1020
1070
|
characters, digits or dashes.
|
|
@@ -1160,7 +1210,20 @@ output.
|
|
|
1160
1210
|
|
|
1161
1211
|
## Links and Images
|
|
1162
1212
|
|
|
1163
|
-
|
|
1213
|
+
Three types of links are supported: autolinks, inline links and reference links.
|
|
1214
|
+
|
|
1215
|
+
### Autolinks
|
|
1216
|
+
|
|
1217
|
+
This is the easiest one to create: Just surround a web address or an email address with angle
|
|
1218
|
+
brackets and the address will be turned into a proper link. The address will be used as link target
|
|
1219
|
+
and as link text. For example:
|
|
1220
|
+
|
|
1221
|
+
Information can be found on the <http://example.com> homepage.
|
|
1222
|
+
You can also mail me: <me.example@example.com>
|
|
1223
|
+
|
|
1224
|
+
It is not possible to specify a different link text using autolinks -- use the other link types for
|
|
1225
|
+
this!
|
|
1226
|
+
|
|
1164
1227
|
|
|
1165
1228
|
### Inline Links
|
|
1166
1229
|
|
|
@@ -1244,42 +1307,30 @@ The link definition for images is exactly the same as the link definition for no
|
|
|
1244
1307
|
|
|
1245
1308
|
## Emphasis
|
|
1246
1309
|
|
|
1247
|
-
kramdown
|
|
1248
|
-
|
|
1249
|
-
surrounded with two asterisks or underscores are
|
|
1250
|
-
starting delimiter must not be followed by a space and that the stopping delimiter
|
|
1251
|
-
preceded by a space.
|
|
1310
|
+
kramdown supports two types of emphasis: light and strong emphasis. Text parts that are surrounded
|
|
1311
|
+
with single asterisks `*` or underscores `_` are treated as text with light emphasis, text parts
|
|
1312
|
+
surrounded with two asterisks or underscores are treated as text with strong emphasis. Surrounded
|
|
1313
|
+
means that the starting delimiter must not be followed by a space and that the stopping delimiter
|
|
1314
|
+
must not be preceded by a space.
|
|
1315
|
+
|
|
1316
|
+
Here is an example for text with light and strong emphasis:
|
|
1252
1317
|
|
|
1253
1318
|
*some text*
|
|
1254
1319
|
_some text_
|
|
1255
1320
|
**some text**
|
|
1256
1321
|
__some text__
|
|
1257
1322
|
|
|
1258
|
-
will produce the following output:
|
|
1259
|
-
|
|
1260
|
-
<em>some text</em>
|
|
1261
|
-
<em>some text</em>
|
|
1262
|
-
<strong>some text</strong>
|
|
1263
|
-
<strong>some text</strong>
|
|
1264
|
-
|
|
1265
1323
|
The asterisk form is also allowed within a single word:
|
|
1266
1324
|
|
|
1267
1325
|
This is un*believe*able! This d_oe_s not work!
|
|
1268
1326
|
|
|
1269
|
-
Text
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
This is a ***strong and emphasized*** text.
|
|
1273
|
-
This **is __very__ strong**.
|
|
1274
|
-
This **is **very** strong**.
|
|
1275
|
-
|
|
1276
|
-
will produce the following output:
|
|
1327
|
+
Text can be marked up with both light and strong emphasis, possibly using different delimiters.
|
|
1328
|
+
However, it is not possible to nest strong within strong or light within light emphasized text:
|
|
1277
1329
|
|
|
1278
|
-
|
|
1279
|
-
This
|
|
1280
|
-
This
|
|
1281
|
-
|
|
1282
|
-
Notice the difference between the second and the third line!
|
|
1330
|
+
This is a ***text with light and strong emphasis***.
|
|
1331
|
+
This **is _emphasized_ as well**.
|
|
1332
|
+
This *does _not_ work*.
|
|
1333
|
+
This **does __not__ work either**.
|
|
1283
1334
|
|
|
1284
1335
|
If one or two asterisks or underscores are surrounded by spaces, they are treated literally. If you
|
|
1285
1336
|
want to force the literal meaning of an asterisk or an underscore you can backslash-escape it:
|
|
@@ -1296,20 +1347,16 @@ by surrounding it with backticks `` ` ``. For example:
|
|
|
1296
1347
|
|
|
1297
1348
|
Use `<html>` tags for this.
|
|
1298
1349
|
|
|
1299
|
-
|
|
1300
|
-
|
|
1350
|
+
Note that all special characters in a code span are treated correctly. For example, when a code span
|
|
1351
|
+
is converted to HTML, the characters `<`, `>` and `&` are substituted by their respective HTML
|
|
1352
|
+
counterparts.
|
|
1301
1353
|
|
|
1302
1354
|
To include a literal backtick in a code span, you need to use two or more backticks as delimiters.
|
|
1303
1355
|
You can insert one optional space after the starting and before the ending delimiter (these spaces
|
|
1304
1356
|
are not used in the output). For example:
|
|
1305
1357
|
|
|
1306
1358
|
Here is a literal `` ` `` backtick.
|
|
1307
|
-
And here is `` `some` `` text (note the two spaces!).
|
|
1308
|
-
|
|
1309
|
-
will produce:
|
|
1310
|
-
|
|
1311
|
-
<p>Here is a literal <code>`</code> backtick.</p>
|
|
1312
|
-
<p>And here is <code> `some` </code> text (note the two spaces!).</p>
|
|
1359
|
+
And here is `` `some` `` text (note the two spaces so that one is left in the output!).
|
|
1313
1360
|
|
|
1314
1361
|
A single backtick surrounded by spaces is treated as literal backtick. If you want to force the
|
|
1315
1362
|
literal meaning of a backtick you can backslash-escape it:
|
|
@@ -1327,7 +1374,7 @@ you have to use, for example, `<br />` instead of `<br>` (although kramdown trie
|
|
|
1327
1374
|
if possible).
|
|
1328
1375
|
|
|
1329
1376
|
By default, kramdown parses kramdown syntax inside span HTML tags. However, this behaviour can be
|
|
1330
|
-
configured with the
|
|
1377
|
+
configured with the `parse_span_html` option. If this is set to `true`, then syntax parsing in HTML
|
|
1331
1378
|
spans is enabled, if it is set to `false`, parsing is disabled. It is also possible to
|
|
1332
1379
|
enable/disable syntax parsing on a tag per tag basis using the `markdown` attribute:
|
|
1333
1380
|
|
|
@@ -1434,6 +1481,26 @@ foot note definitions are ignored. If more than one footnote definitions have th
|
|
|
1434
1481
|
name, all footnote definitions but the last are ignored.
|
|
1435
1482
|
|
|
1436
1483
|
|
|
1484
|
+
## Typographic Symbols
|
|
1485
|
+
|
|
1486
|
+
> The original Markdown syntax does not support these transformations.
|
|
1487
|
+
{: .markdown-difference}
|
|
1488
|
+
|
|
1489
|
+
kramdown converts the following plain ASCII character into their corresponding typographic symbols:
|
|
1490
|
+
|
|
1491
|
+
* `---` will become an em-dash (like this ---)
|
|
1492
|
+
* `--` will become an en-dash (like this --)
|
|
1493
|
+
* `...` will become an ellipsis (like this ...)
|
|
1494
|
+
* `<<` will become a left guillemet (like this <<) -- an optional following space will become a
|
|
1495
|
+
non-breakable space
|
|
1496
|
+
* `>>` will become a right guillemet (like this >>) -- an optional leading space will become a
|
|
1497
|
+
non-breakable space
|
|
1498
|
+
|
|
1499
|
+
It also replaces normal single `'` and double quotes `"` with "fancy quotes". There *may* be times
|
|
1500
|
+
when kramdown falsely replace the quotes. If this is the case, just \'escape\" the quotes and they
|
|
1501
|
+
won't be replaced with fancy ones.
|
|
1502
|
+
|
|
1503
|
+
|
|
1437
1504
|
## Span Inline Attribute Lists
|
|
1438
1505
|
|
|
1439
1506
|
> This syntax feature is not part of the original Markdown syntax. The idea and syntax comes from
|
|
@@ -1442,8 +1509,8 @@ name, all footnote definitions but the last are ignored.
|
|
|
1442
1509
|
|
|
1443
1510
|
This is a version of the [block inline attribute list](#block-inline-attribute-lists) for span level
|
|
1444
1511
|
elements. It has the same structure as the block IAL except that leading and trailing spaces are not
|
|
1445
|
-
allowed. A span IAL (or two or more span IALs) has to be put directly after the span level element
|
|
1446
|
-
no additional character is allowed between.
|
|
1512
|
+
allowed. A span IAL (or two or more span IALs) has to be put directly after the span level element
|
|
1513
|
+
to which it should be applied, no additional character is allowed between.
|
|
1447
1514
|
|
|
1448
1515
|
Here are some examples for span IALs:
|
|
1449
1516
|
|