Markeven Syntax Guide

Block elements

Markeven recognizes following block-level elements:

Block elements are always delimited by two or more line ends (\n\n):

This is a paragraph

    this is a code block

    But this is still
a paragraph.

This behavior is different from Markdown, which interprets last block as two blocks: paragraph and code block.


A paragraph is simply one or more lines of text. Multiple lines are joined into a single paragraph:

Paragraph one.

Paragraph two.
More text.

Paragraph three.
More text.
Even more text.

Following markup will be generated:

<p>Paragraph one.</p>
<p>Paragraph two. More text.</p>
<p>Paragraph three. More text. Even more text.</p>

Like in Markdown, if you wish to place linebreak, leave two or more space characters at the end of the line.

Sections (divs)

Section is a block which is rendered into an HTML div element. Each line of a section must start with a pipe | character:

| This is a section with two paragraphs.
| I am the first one.
| And I am the second one.

Following markup will be generated:

  <p>This is a section with two paragraphs.  I am the first one.</p>
  <p>And I am the second one.</p>

Sections are frequently used in conjunction with block selectors by web designers to achieve certain effects like styling, animating, etc.


Markeven supports both ATX and Setex styles proposed by Markdown:

This is first-level heading

This is second-level heading

# First level again

## Second level here

### Third level

#### Fourth level

##### Fifth level

###### Sixth level

Unline Markdown, Markeven do not allow closing #s, so following example:

# This is a heading which ends with #

will be transformed into:

<h1>This is a heading which ends with #</h1>

Preformatted code blocks

Code blocks are used to write about programming or markup stuff. Their contents is usually rendered using monospaced font and is interpreted literally. To produce a code block, indent every line of block with at least 4 spaces or 1 tab:

Here's some code:

    println("Hello world!")

Markeven will produce:

<p>Here's some code:</p>
<pre><code>println("Hello world!")

Ordered and unordered lists

Lists in Markeven have strict rules which help you build highly structured documents.

The first thing to know about is a list marker. Ordered lists must start with 1. followed by at least one space. Unordered lists must start with * followed by at least one space. Every subsequent list item must start with the same marker (a number followed by a dot and whitespace in case of ordered lists):

1. list item 1
2. list item 2

* list item 1
* list item 2

Here is generated markup for the above snippet:

  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 1</li>
  <li>list item 2</li>

Lists items can contain another block-level elements. To interpret whitespace-sensitive blocks properly, you should maintain the same indentation inside list items. We refer to this indentation as list item baseline:

*  This paragraph is under first list item.

   This paragraph is also under first list item, because
   it is properly indented.

*     This list item has another baseline.

      So we should indent our second paragraph accordingly.

This paragraph, however, is outside list.

Following markup will be generated:

    <p>This paragraph is under first list item.</p>
    <p>This paragraph is also under first list item, because it is properly indented.</p>
    <p>This list item has another baseline.</p>
    <p>So we should indent our second paragraph accordingly.</p>
<p>This paragraph, however, is outside list.</p>

Nested lists follow the same rules:

1. List 1 item 1

2. List 1 item 2

   1. List 2 item 1

   2. List 2 item 2

3. List 1 item 3

Codeblocks can also be nested inside list items. Each line of a code block must be indented with at least 4 spaces or 1 tab relatively to list item's baseline:

1.  Code inside list item:

        def sayHello = {
          println("Hello world!")

You can also add a visual guide indicating current list item baseline using the pipe | character. It can be useful in cases when the list item is long and its content is complex:

1.   | This is a long and complex list item.
     |    code block
     |  * another list
     |  * ...

2. And that's it.

Note that list items belong to the same list only if their markers are equaly indented. Following example shows two different lists:

  * List one item one

  * List one item two

* List two item one

* List two item two

And a paragraph.

Here's the markup:

  <li>List one item one</li>
  <li>List one item two</li>
  <li>List two item one</li>
  <li>List two item two</li>
<p>And a paragraph.</p>


Markeven supports simple syntax for tables:

|   Column 1  |   Column 2   |   Column 3   |
| one         | two          | three        |
| four        | five         | six          |

Here's the markup:

      <th>Column 1</th>
      <th>Column 2</th>
      <th>Column 3</th>

As you can see, the first and the last line of table should consist of minus - characters only. The only exception to this rule is that the first line can optionally end with > character. If > character is there, the width of table will expand to its maximum.

Cells are separated by the pipe | character, you can omit leading and trailing pipes. Table header is separated from table body by the separator line. This line can optionally contain semicolon : characters to express column alignment: a semicolon to the left side means left alignment, a semicolon to the right side means right alignment, two semicolons at both ends means center alignment:

|   Column 1  |   Column 2   |   Column 3   |
|         one |      two     | three        |
|        four |     five     | six          |

You can also omit the header, in this case you cannot specify column alignment with semicolons:

one  | two  | three


Blockquotes are similar to sections, but they are rendered into HTML blockquote element. Each line of a blockquote must start with > character. Like sections, blockquotes can contain nested block elements:

> This is blockquote.
> > This blockquote is nested.
> That's it.

Here's generated markup:

  <p>This is blockquote.</p>
  <blockquote>This blockquote is nested.</blockquote>
  <p>That's it.</p>

Horizontal rulers

A horizontal ruler is rendered from a block which contains three or more minus - characters:

This is some text.


This is some more text.

Following markup will be produced by Markeven:

<p>This is some text.</p>
<p>This is some more text.</p>

No other syntaxes for <hr/> are supported.

Inline HTML

Markeven allows you to place HTML elements right inside your text. Their content won't get processed:


    This text won't get transformed into a code block


    But this will.

There are no strict rules about inline HTML. The only important thing is that your markup should be correct (tags closed and properly nested). Markeven does not have the ability to “fix” wrong HTML markup yet :)

Block selectors

Each block can optionally have a selector. It is used to add id and class HTML attributes to blocks:

I have an id.                     {#para1}

I have two classes.               {.class1.class2}

I have an id and a class.         {#para3.class1}

The example above will be transformed into a following HTML snippet:

<p id="para1">I have an id.</p>
<p class="class1 class2">I have two classes.</p>
<p id="para3" class="class1">I have an id and a class.</p>

The most common use of selectors is to assign id attribute so that they can be used in links:

Now I can be referenced by id!        {#mypara}

Look! I can reference [another paragraph](#mypara).

The selector expression is enclosed into curly braces and must be placed at the end of the first line of the block (no trailing whitespace allowed!).

Text enhancements

Inside block level elements following text enhancements occur:

You can also use backslash escaping to prevent misinterpreting special characters. Following characters can be escaped: \`_*{}[]()#+-~.!

Links & Images

Two style of links are supported: inline and reference.

Inline links look like this: [my text](http://my_url) or [some text](http://some_url "some title") and are rendered into HTML a element: <a href="http://my_url">my text</a> and <a href="http://some_url" title="some title">some text</a>.

Reference-style links are split into link definition and link usage. Using previous examples, here's how link definitions could look like:

[id1]: http://my_url
[id2]: http://some_url "some title"

Link usages would then look like this: [my text][id1] and [some text][id2]. The generated markup is equal to the previous one.

The syntax for images is similar to the one for links: the exclamation ! sign immediately before opening bracket tells markeven to interpret the link as an image. Link text becomes the value of alt attribute:

Inline image: ![some image](/img/hello.png "Hello")

Or reference-style image: ![some image][img]

  [img]: /img/hello.png "Hello"

Both cases generate following markup for image:

<img src="/img/hello.png" title="Hello" alt="some image"/>