Changesets can be listed by changeset number.
The Git repository is here.
- Revision:
- 373
- Log:
Initial import of Radiant 0.9.1, which is now packaged as a gem. This is an
import of the tagged 0.9.1 source checked out from GitHub, which isn't quite
the same as the gem distribution - but it doesn't seem to be available in an
archived form and the installed gem already has modifications, so this is
the closest I can get.
- Author:
- rool
- Date:
- Mon Mar 21 13:40:05 +0000 2011
- Size:
- 14997 Bytes
1 | --- |
2 | title: Quick Reference |
3 | in_menu: true |
4 | sort_info: 9 |
5 | --- name:sidebar |
6 | <h1>Contents</h1> |
7 | |
8 | {menu: {used_nodes: fragments, min_levels: 4, max_levels: 6}} |
9 | --- name:content |
10 | # Quick Reference |
11 | |
12 | Below are examples of all available structural elements that can be used in a kramdown text. Since |
13 | the kramdown syntax is a superset of the Markdown syntax, only a small part of the available syntax |
14 | is not available in standard Markdown syntax. Note, that only the most basic syntax information is |
15 | given. However, a link to the detailed syntax for each element is provided (which also details the |
16 | differences to the standard Markdown syntax). The quick reference is for version **<%= |
17 | ::Kramdown::VERSION %>** of the syntax documentation. |
18 | |
19 | kramdown has two main classes of elements: block and span level elements. Block level elements are |
20 | used to create paragraphs, headers, lists and so on whereas span level elements are used to markup |
21 | text phrases as emphasized, as a link and so on. |
22 | |
23 | All examples below feature the kramdown source, the converted HTML source and the output as it |
24 | appears in the browser. This looks like this: |
25 | |
26 | <div class="kdexample"> |
27 | <pre class="kdexample-before"><code>kramdown example code</code></pre> |
28 | <pre class="kdexample-after-source"><code>Example code converted to HTML</code></pre> |
29 | <div class="kdexample-after-live" style="clear:none"> |
30 | Live browser view of example code |
31 | </div> |
32 | </div> |
33 | <div class="clear"></div> |
34 | |
35 | |
36 | # Block Level Elements - Main Structural Elements |
37 | |
38 | ## Paragraphs |
39 | |
40 | {kdlink: {oid: paragraphs, part: "paragraphs"}} |
41 | |
42 | Paragraphs are separated by one or more blank lines: |
43 | |
44 | {kdexample::} |
45 | The first paragraph. |
46 | |
47 | Another paragraph |
48 | {kdexample} |
49 | |
50 | Explicit line breaks in a paragraph can be made by using two spaces or two backslashes at the end of a line: |
51 | |
52 | {kdexample::} |
53 | This is a paragraph |
54 | which contains a hard line break. |
55 | {kdexample} |
56 | |
57 | |
58 | ## Headers |
59 | |
60 | {kdlink: {oid: headers, part: "headers"}} |
61 | |
62 | kramdown supports Setext style headers and atx style headers. A header must always be preceded by a |
63 | blank line except at the beginning of the document: |
64 | |
65 | {kdexample::} |
66 | First level header |
67 | ================== |
68 | |
69 | Second level header |
70 | ------------------- |
71 | {kdexample} |
72 | |
73 | {kdexample::} |
74 | # H1 header |
75 | |
76 | ## H2 header |
77 | |
78 | ### H3 header |
79 | |
80 | #### H4 header |
81 | |
82 | ##### H5 header |
83 | |
84 | ###### H6 header |
85 | {kdexample} |
86 | |
87 | If you set the option `auto_ids` to `false` (for example, by using the `options` extension, see |
88 | [Extensions](#extensions)), then the automatic header ID generation is turned off: |
89 | |
90 | {kdexample::} |
91 | {:options auto_ids="false" /} |
92 | |
93 | # A header without an ID |
94 | {kdexample} |
95 | |
96 | |
97 | ## Blockquotes |
98 | |
99 | {kdlink: {oid: blockquotes, part: "blockquotes"}} |
100 | |
101 | A blockquote is started using the `>` marker followed by an optional space; all following lines that |
102 | are also started with the blockquote marker belong to the blockquote. You can use any block level |
103 | elements inside a blockquote: |
104 | |
105 | {kdexample::} |
106 | > A sample blockquote. |
107 | > >Nested blockquotes are |
108 | > >also possible. |
109 | > |
110 | > ## Headers work too |
111 | > This is the outer quote again. |
112 | {kdexample} |
113 | |
114 | |
115 | ## Code Blocks |
116 | |
117 | {kdlink: {oid: code-blocks, part: "code blocks"}} |
118 | |
119 | kramdown supports two different code block styles. One uses lines indented with either four spaces |
120 | or one tab whereas the other uses lines with tilde characters as delimiters -- therefore the content |
121 | does not need to be indented: |
122 | |
123 | {kdexample::} |
124 | This is a sample code block. |
125 | |
126 | Continued here. |
127 | {kdexample} |
128 | |
129 | {kdexample::} |
130 | ~~~~~~ |
131 | This is also a code block. |
132 | ~~~ |
133 | Ending lines must have at least as |
134 | many tildes as the starting line. |
135 | ~~~~~~~~~~~~ |
136 | {kdexample} |
137 | |
138 | |
139 | ## Horizontal Rules |
140 | |
141 | {kdlink: {oid: horizontal-rules, part: "horizontal rules"}} |
142 | |
143 | It is easy to insert a horizontal rule in kramdown: just use three or more asterisks, dashes or |
144 | underscores, optionally separated by spaces or tabs, on an otherwise blank line: |
145 | |
146 | {kdexample::} |
147 | * * * |
148 | |
149 | \--- |
150 | |
151 | _ _ _ _ |
152 | |
153 | --------------- |
154 | {kdexample} |
155 | |
156 | |
157 | ## Lists |
158 | |
159 | {kdlink: {oid: lists, part: "lists"}} |
160 | |
161 | kramdown supports ordered and unordered lists. Ordered lists are started by using a number followed |
162 | by a period, a space and then the list item text. The content of a list item consists of block level |
163 | elements. All lines which have the same indent as the text of the line with the list marker belong |
164 | to the list item: |
165 | |
166 | {kdexample::} |
167 | 1. This is a list item |
168 | 2. And another item |
169 | 2. And the third one |
170 | with additional. text |
171 | {kdexample} |
172 | |
173 | As the content consists of block level elements you can do things like the following: |
174 | |
175 | {kdexample::} |
176 | 1. This is a list item |
177 | |
178 | > with a blockquote |
179 | |
180 | # And a header |
181 | |
182 | 2. Followed by another item |
183 | {kdexample} |
184 | |
185 | Nested lists are also easy to create: |
186 | |
187 | {kdexample::} |
188 | 1. Item one |
189 | 1. sub item one |
190 | 2. sub item two |
191 | 3. sub item three |
192 | 2. Item two |
193 | {kdexample} |
194 | |
195 | Lists can occur directly after other block level elements, however, there has to be at least one |
196 | blank line if you want to follow a paragraph with a list: |
197 | |
198 | {kdexample::} |
199 | This is a paragraph. |
200 | 1. This is NOT a list. |
201 | |
202 | 1. This is a list! |
203 | {kdexample} |
204 | |
205 | Unordered lists are started by using an asterisk, a dash or a plus sign (they can be mixed) and a |
206 | space. Apart from that unordered lists follow the same rules as ordered lists: |
207 | |
208 | {kdexample::} |
209 | * Item one |
210 | + Item two |
211 | - Item three |
212 | {kdexample} |
213 | |
214 | ## Definition Lists |
215 | |
216 | {kdlink: {oid: definition-lists, part: "definition lists"}} |
217 | |
218 | A definition list works similar to a normal list and is used to associate definitions with terms. |
219 | Definition lists are started when a normal paragraph is followed by a line starting with a colon and |
220 | then the definition text. One term can have many definitions and multiple terms can have the same |
221 | definition. Each line of the preceding paragraph is assumed to contain one term, for example: |
222 | |
223 | {kdexample::} |
224 | term |
225 | : definition |
226 | : another definition |
227 | |
228 | another term |
229 | and another term |
230 | : and a definition for the term |
231 | {kdexample} |
232 | |
233 | If you insert a blank line before a definition (note: there must only be one blank line between the |
234 | terms and the first definition), the definition will be wrapped in a paragraph: |
235 | |
236 | {kdexample::} |
237 | term |
238 | |
239 | : definition |
240 | : definition |
241 | {kdexample} |
242 | |
243 | Each term can be styled using span level elements and each definition is parsed as block level |
244 | elements, i.e. you can use any block level in a definition. Just use the same indent for the lines |
245 | following the definition line: |
246 | |
247 | {kdexample::} |
248 | This *is* a term |
249 | |
250 | : This will be a para |
251 | > a blockquote |
252 | |
253 | # A header |
254 | {kdexample} |
255 | |
256 | |
257 | ## Tables |
258 | |
259 | {kdlink: {oid: tables, part: "tables"}} |
260 | |
261 | kramdown supports a syntax for creating simple tables. A line starting with a pipe character (`|`) |
262 | starts a table row. However, if the pipe characters is immediately followed by a dash (`-`), a |
263 | separator line is created. Separator lines are used to split the table header from the table body |
264 | (and optionally align the table columns) and to split the table body into multiple parts. If the |
265 | pipe character is followed by an equal sign (`=`), the tables rows below it are part of the table |
266 | footer. |
267 | |
268 | {kdexample::} |
269 | | A simple | table | |
270 | | with multiple | lines| |
271 | {kdexample} |
272 | |
273 | {kdexample::} |
274 | | Header1 | Header2 | Header3 | |
275 | |:--------|:-------:|--------:| |
276 | | cell1 | cell2 | cell3 | |
277 | | cell4 | cell5 | cell6 | |
278 | |---- |
279 | | cell1 | cell2 | cell3 | |
280 | | cell4 | cell5 | cell6 | |
281 | |===== |
282 | | Foot1 | Foot2 | Foot3 |
283 | {: rules="groups"} |
284 | {kdexample} |
285 | |
286 | |
287 | ## HTML elements |
288 | |
289 | {kdlink: {oid: html-blocks, part: "HTML blocks"}} |
290 | |
291 | kramdown allows you to use block level HTML tags (`div`, `p`, `pre`, ...) to markup whole blocks of |
292 | text -- just start a line with a block level HTML tag. kramdown syntax is normally not processed |
293 | inside an HTML tag but this can be changed with the `parse_block_html` option. If this options is |
294 | set to `true`, then the content of a block level HTML tag is parsed by kramdown either as block |
295 | level or span level text, depending on the tag: |
296 | |
297 | {kdexample::} |
298 | <div style="float: right"> |
299 | Something that stays right and is not wrapped in a para. |
300 | </div> |
301 | {options: parse_block_html="true"} |
302 | <div> |
303 | This is wrapped in a para. |
304 | </div> |
305 | <p> |
306 | This can contain only *span* level elements. |
307 | </p> |
308 | {kdexample} |
309 | |
310 | |
311 | ## Block Attributes |
312 | |
313 | {kdlink: {oid: block-inline-attribute-lists, part: "block IALs"}} |
314 | {kdlink: {oid: attribute-list-definitions, part: "ALDs"}} |
315 | |
316 | You can assign any attribute to a block level element. Just directly follow the block with a *block |
317 | inline attribute list* (or short: block IAL). A block IAL consists of a left curly brace, followed |
318 | by a colon, the attribute definitions and a right curly brace. Here is a simple example which sets the |
319 | `title` attribute of a block quote: |
320 | |
321 | {kdexample::} |
322 | > A nice blockquote |
323 | {: title="Blockquote title"} |
324 | {kdexample} |
325 | |
326 | As one often wants to set one or more CSS classes on an element, there is an easy shortcut: |
327 | |
328 | {kdexample::} |
329 | > A nice blockquote |
330 | {: .class1 .class2} |
331 | {kdexample} |
332 | |
333 | A shortcut for setting the ID is also provided. Just prefix the ID with a hash symbol: |
334 | |
335 | {kdexample::} |
336 | > A nice blockquote |
337 | {: #with-an-id} |
338 | {kdexample} |
339 | |
340 | Sometimes one wants to use the same attributes for many elements. kramdown allows you to define the |
341 | attributes in one place with an *attribute list definition* (or short: ALD) and just reference this |
342 | definition in a block IAL. An ALD has the same structure as a block IAL but the colon has to be |
343 | replace with a colon, the reference name and another colon. By just using the reference name as-is |
344 | in a block IAL, one can include the attributes of the referenced ALD: |
345 | |
346 | {kdexample::} |
347 | {:refdef: .c1 #id .c2 title="title"} |
348 | paragraph |
349 | {: refdef} |
350 | {kdexample} |
351 | |
352 | The order in a block IAL or ALD is important because later defined attributes overwrite (with the |
353 | exception of the shortcut for CSS classes) prior defined attributes: |
354 | |
355 | {kdexample::} |
356 | {:refdef: .c1 #id .c2 title="title"} |
357 | paragraph |
358 | {: refdef .c3 title="t" #para} |
359 | {kdexample} |
360 | |
361 | |
362 | ## Extensions |
363 | |
364 | {kdlink: {oid: extensions, part: "extensions"}} |
365 | |
366 | kramdown provides some less used functionality through a common syntax. This will allow the easy |
367 | addition of other extensions if need arises. Currently, there are extensions for ignoring text (i.e. |
368 | treating text as comment), for inserting arbitrary text as-is into the output and for setting |
369 | kramdown options. |
370 | |
371 | Here is an example that shows how to insert comments into text: |
372 | |
373 | {kdexample::} |
374 | This is a paragraph |
375 | {:comment} |
376 | This is a comment which is |
377 | completely ignored. |
378 | {:/comment} |
379 | ... paragraph continues here. |
380 | |
381 | Extensions can also be used |
382 | inline {:nomarkdown}**see**{:/}! |
383 | {kdexample} |
384 | |
385 | As one can see from the above example, the syntax for extensions is nearly identical to that of |
386 | ALDs. However, there is no trailing colon after the extension name and the extension end tag needs a |
387 | slash between the colon and the extension name. One can also use the short form of the end tag, i.e. |
388 | `{:/}`. Attribute definitions can be specified on the start tag by separating them with a space from |
389 | the extension name. Also, if the extension does not have a body, there needs to be a slash right |
390 | before the closing brace: |
391 | |
392 | {kdexample::} |
393 | {:options auto_ids="false" /} |
394 | |
395 | # Header without id |
396 | {kdexample} |
397 | |
398 | |
399 | |
400 | |
401 | # Span Level Elements - Text Modifiers |
402 | |
403 | ## Emphasis |
404 | |
405 | {kdlink: {oid: emphasis, part: "emphasis"}} |
406 | |
407 | Emphasis can be added to text by surrounding the text with either asterisks or underscores: |
408 | |
409 | {kdexample::} |
410 | This is *emphasized*, |
411 | _this_ too! |
412 | {kdexample} |
413 | |
414 | Strong emphasis can be done by doubling the delimiters: |
415 | |
416 | {kdexample::} |
417 | This is **strong**, |
418 | __this__ too! |
419 | {kdexample} |
420 | |
421 | The form with the asterisks can also be used to markup parts of words: |
422 | |
423 | {kdexample::} |
424 | This w**ork**s as expected! |
425 | {kdexample} |
426 | |
427 | |
428 | ## Links and Images |
429 | |
430 | {kdlink: {oid: links-and-images, part: "links and images"}} |
431 | |
432 | A simple link can be created by surrounding the text with square brackets and the link URL with |
433 | parentheses: |
434 | |
435 | {kdexample::} |
436 | A [link](http://kramdown.rubyforge.org) |
437 | to the kramdown homepage. |
438 | {kdexample} |
439 | |
440 | You can also add title information to the link: |
441 | |
442 | {kdexample::} |
443 | A [link](http://kramdown.rubyforge.org "hp") |
444 | to the homepage. |
445 | {kdexample} |
446 | |
447 | There is another way to create links which does not interrupt the text flow. The URL and title are |
448 | defined using a reference name and this reference name is then used in square brackets instead of |
449 | the link URL: |
450 | |
451 | {kdexample::} |
452 | A [link][kramdown hp] |
453 | to the homepage. |
454 | |
455 | [kramdown hp]: http://kramdown.rubyforge.org "hp" |
456 | {kdexample} |
457 | |
458 | If the link text itself is the reference name, the second set of square brackets can be omitted: |
459 | |
460 | {kdexample::} |
461 | A link to the [kramdown hp]. |
462 | |
463 | [kramdown hp]: http://kramdown.rubyforge.org "hp" |
464 | {kdexample} |
465 | |
466 | Images can be created in a similar way: just use an exclamation mark before the square brackets. The |
467 | link text will become the alternative text of the image and the link URL specifies the image source: |
468 | |
469 | {kdexample::} |
470 | An image: ![gras](img/image.jpg) |
471 | {kdexample} |
472 | |
473 | |
474 | ## Inline Code |
475 | |
476 | {kdlink: {oid: code-spans, part: "code spans"}} |
477 | |
478 | Text phrases can be easily marked up as code by surrounding them with backticks: |
479 | |
480 | {kdexample::} |
481 | Use `Kramdown::Document.new(text).to_html` |
482 | to convert the `text` in kramdown |
483 | syntax to HTML. |
484 | {kdexample} |
485 | |
486 | If you want to use literal backticks in your code, just use two or more backticks as delimiters. The |
487 | space right after the beginning delimiter and the one right before the closing delimiter are ignore: |
488 | |
489 | {kdexample::} |
490 | Use backticks to markup code, |
491 | e.g. `` `code` ``. |
492 | {kdexample} |
493 | |
494 | |
495 | ## Footnotes |
496 | |
497 | {kdlink: {oid: footnotes, part: "footnotes"}} |
498 | |
499 | Footnotes can easily be used in kramdown. Just set a footnote marker (consists of square brackets |
500 | with a caret and the footnote name inside) in the text and somewhere else the footnote definition (which |
501 | basically looks like a reference link definition): |
502 | |
503 | {kdexample::} |
504 | This is a text with a |
505 | footnote[^1]. |
506 | |
507 | [^1]: And here is the definition. |
508 | {kdexample} |
509 | |
510 | The footnote definition can contain any block level element, all lines following a footnote |
511 | definition indented with four spaces or one tab belong to the definition: |
512 | |
513 | {kdexample::} |
514 | This is a text with a |
515 | footnote[^2]. |
516 | |
517 | [^2]: |
518 | And here is the definition. |
519 | |
520 | > With a quote! |
521 | {kdexample} |
522 | |
523 | As can be seen above the footnote name is only used for the anchors and the numbering is done |
524 | automatically in document order. |
525 | |
526 | |
527 | ## Abbreviations |
528 | |
529 | {kdlink: {oid: abbreviations, part: "abbreviations"}} |
530 | |
531 | Abbreviations will work out of the box once you add an abbreviation definition. So you can just |
532 | write the text and add the definitions later on. |
533 | |
534 | {kdexample::} |
535 | This is an HTML |
536 | example. |
537 | |
538 | *[HTML]: Hyper Text Markup Language |
539 | {kdexample} |
540 | |
541 | |
542 | ## HTML Elements |
543 | |
544 | {kdlink: {oid: html-spans, part: "HTML spans"}} |
545 | |
546 | HTML is not only supported on the block level but also on the span level: |
547 | |
548 | {kdexample::} |
549 | This is <span style="color: red">written in |
550 | red</span>. |
551 | {kdexample} |
552 | |
553 | |
554 | ## Inline Attributes |
555 | |
556 | {kdlink: {oid: span-inline-attribute-lists, part: "span IALs"}} |
557 | |
558 | As with a block level element you can assign any attribute to a span level elements using a *span |
559 | inline attribute list* (or short: span IAL). A span IAL has the same syntax as a block IAL and must |
560 | immediately follow the span level element: |
561 | |
562 | {kdexample::} |
563 | This is *red*{: style="color: red"}. |
564 | {kdexample} |