Official Syntax


1. Introduction

Here is the official core of Skriv Markup's syntax.

1.1 Version

The Skriv Markup syntax' current version is alpha.

1.2 Escaping

All special characters are escaped. For instance, less-than (<), greatear-than (>) and ampersand (&) characters are transformed during HTML export (respectively to &lt;, &gt; and &amp;).

Sometimes, it's necessary to prevent some language interpretation, when you want to display something that should be used as a markup. To do so, you just have to put a backslash (\) character in front of the markup.

Reasoning
The backslash character is commonly used to escape sequences in text streams, in many programming languages. More, this character is rarely used in normal texts, so in shouldn't conflict with any other typed characters.

1.3 Note about spaces

You'll see that some markups can take several parameters; in this case, the parameters are separated with a pipe character (|). You can add spaces before and/or after any parameter, they will be removed afterward.

For example, these four lines produce the exact same link:

[[Skriv|http://skriv.org]]
[[ Skriv | http://skriv.org ]]
[[Skriv | http://skriv.org]]
[[Skriv |http://skriv.org]]

In fact, spaces are removed when they are obviously optional. These two lists produce the exact same result:

*AAA
*BBB

* AAA
* BBB

As well as these two titles:

==Level 2 title==
== Level 2 title ==

And for these tables:

!!Head 1!!Head 2
||Cell 1||Cell 2

!! Head 1 !! Head 2
|| Cell 1 || Cell 2

On the other hand, inline markups without parameters don't remove spaces. So these two lines are different:

**bold text** and ''italic text''
** bold text ** and '' italic text ''

2. Paragraphs

Out of special blocks, any text is placed inside a paragraph. Paragraphs are separated by one or more blank line. Inside a paragraph, line-breaks are kept as they are typed.

Skriv Markup
Here is the first paragraph.
With two lines.

Here is the second paragraph, with
many
carriage-returns.
Result

Here is the first paragraph.
With two lines.

Here is the second paragraph, with
many
carriage-returns.

HTML
<p>
    Here is the first paragraph.<br />
    With two lines.
</p>
<p>
    Here is the second paragraph, with<br />
    many<br />
    carriage-returns.
</p>
Reasoning

Paragraphs are so common that no explicit markup should be necessary to create them.

Keep line-breaks seems the best way to ensure a result as close as possible from what the writer wants. This point of view is shared by GitHub Flavored Markdown.

3. Basic styles

Inline styles are marked up using tags before and after the affected text. These tags are constituted by two identical characters.
These markups can affect full-words only, they are not effective if they are written in the middle of a word.

Skriv Markup
works on**ly on full** words
Output
works on**ly on full** words
Reasoning
Most of the time, it's totally pointless to apply a style on a chuck of a word. Usually, that could lead to a misunderstanding of the writer's will. Here again, this point of view is shared by GitHub Flavored Markdown.

3.1 Italic

Skriv Markup
two ''single quotes'' for italic
Output
two single quotes for italic
HTML
two <em>single quotes</em> for italic
Reasoning
For light emphasis, the doubled-single-quotes markup is widely used (MediaWiki). The doubled-slash characters (//), used by Creole, is pretty logical; the shape of the slash character reminds the slanted aspect of italic writing. But the visual impact on the text is overweening compared with the desired result.

3.2 Strong

Skriv Markup
two **asterisks** for bold
Output
two asterisks for bold
HTML
two <strong>asterisks</strong> for bold
Reasoning
Asterisks are commonly used for strong emphasis (Creole, Markdown, txt2tags, DokuWiki). They are also used in emails since the down of time.

3.3 Underline

Skriv Markup
two __underscores__ for underline
Output
two underscores for underline
HTML
two <u>underscores</u> for underline
Reasoning

Adding underscores before and after is the perfect markup for underlining, as they are suggesting the beginning and the end of the under line.

This syntax is already used by Creole and DokuWiki.

3.4 Strikeout

Skriv Markup
two --minus signs-- for striking out
Output
two minus signs for striking out
HTML
two <s>minus signs</s> for striking out
Reasoning
The minus signs are good for striked out text, for the same reason than the underscores for underlining.

3.5 Monospace

Skriv Markup
two ##hash signs## for monospace
Output
two hash signs for monospace
HTML
two <tt>hash signs</tt> for monospace
Reasoning

Hash signs have a very special shape. Their more-or-less squared look is a valid metaphor for monospaced fonts.

This syntax is already used by Creole.

3.6 Superscript

Skriv Markup
two ^^caret characters^^ for exponent
Output
two caret characters for exponent
HTML
two <sup>cart characters</sup> for exponent
Reasoning

Caret characters are like little arrowheads indicating upside direction.

This syntax is already used by Creole.

3.7 Subscript

Skriv Markup
two ,,commas,, for subscript
Output
two commas for subscript
HTML
two <sub>commas</sub> for subscript
Reasoning

On the contrary, commas are going under the text's baseline, thus they are suggesting to push down the text.

This syntax is already used by Creole.

4. Titles

4.1 Main syntax

Titles are written using one to six equal signs (=) at the beginning of the line. One equal sign for a first level heading; six equal signs for a sixth level heading.

For esthetical reasons, it's possible to add as many equal signs at the end of the line than at the beginning. They will be removed.
Spaces are allowed between the markups and the title's text.

On HTML output, DOM identifier should be added. It should be possible to prepend a given prefix at the beginning of these identifiers.

Skriv Markup
=Level 1 heading
== Level 2 heading==
===Level 3 heading ===
==== Level 4 heading
HTML
<h1 id="Level-1-heading">Level 1 heading<h1>
<h2 id="Level-2-heading">Level 2 heading<h2>
<h3 id="Level-3-heading">Level 3 heading<h3>
<h4 id="Level-4-heading">Level 4 heading<h4>
Reasoning

Equals signs are a very widespread mean to write headings among wiki syntaxes (MediaWiki, Creole, txt2tags, DokuWiki).

It's a convenient writing, very fast to type. The visual impact is clear; with more equal signs at the beginning of the line, the title is more indented, indicating a sub-header.

Equals signs at the end of the line are optional, because some existing wiki syntaxes made it mandatory, some others avoid them.

4.2 User-defined identifiers

Because two titles may have the same text, two titles may have the same DOM identifier. It could be a real problem when creating links pointing to these titles (even for automatically created table of contents).

To circumvent this problem, it is possible to override a title identifier by writing it at the end of the line, using the balanced markup.

It's always possible to disable this feature, by using the usual escaping character (backslash) before the equal signs, or by using the balanced markup all the time.

Skriv Markup
===Darth Vador
===Darth Vador===
===Darth Vador===your father
=Darth Vador \= your father
=Darth Vador = your father=
HTML
<h3 id="Darth-Vador">Darth Vador</h3>
<h3 id="Darth-Vador">Darth Vador</h3>
<h3 id="your-father">Darth Vador</h3>
<h1 id="Darth-Vador-your-father">Darth Vador = your father<h1>
<h1 id="Darth-Vador-your-father">Darth Vador = your father<h1>
Reasoning
This syntax is the simplest way to define special identifiers, without any fancy addition.

5. Lists

5.1 Unordered lists

Unordered lists are also known as “bulleted-lists”. They are written using asterisk characters (*), placed at the beginning of the lines. There must be no space before the asterisks.

Sub-lists are created by typing more asterisks.

Skriv Markup
* Item 1
* Item 2
** Sub-item 2.1
** Sub-item 2.2
*** Sub-item 2.2.1
Output
  • Item 1
  • Item 2
    • Sub-item 2.1
    • Sub-item 2.2
      • Sub-item 2.2.1
HTML
<ul>
    <li>Item 1</li>
    <li>Item 2
        <ul>
            <li>Sub-item 2.1</li>
            <li>Sub-item 2.2
                <ul>
                    <li>Sub-item 2.2.1</li>
                </ul>
            </li>
        </ul>
    </li>
</ul>
Reasoning

Asterisks character are commonly used to create lists (MediaWiki, Creole, Markdown, reStructuredText, POD, Asciidoc, Textile, WikiWikiWeb, TWiki, MoinMoin, Redmine, ...).

Adding more asterisks at the beginning of the line indent the text as a result. This indentation makes clear where the sublist is.

5.2 Ordered lists

Items of ordered lists are displayed with an incremented number in front of them. They are written using hash signs (#), placed at the beginning of the lines. There must be no space before the hash signs.

Sub-lists are created by typing more hash signs.

Skriv Markup
# Item 1
# Item 2
## Sub-item 2.1
## Sub-item 2.2
### Sub-item 2.2.1
Output
  1. Item 1
  2. Item 2
    1. Sub-item 2.1
    2. Sub-item 2.2
      1. Sub-item 2.2.1
HTML
<ul>
    <li>Item 1</li>
    <li>Item 2
        <ul>
            <li>Sub-item 2.1</li>
            <li>Sub-item 2.2
                <ol>
                    <li>Sub-item 2.2.1</li>
                </ol>
            </li>
        </ul>
    </li>
</ul>
Reasoning

The hash sign is a character used to represent numbers, so its usage is understandable for numbered lists. It's also used by many other languages (MediaWiki, Creole, Textile, Redmine, ...).

The same mechanisms than for unordered lists are applied, to keep a coherent syntax.

5.3 Mixed lists

It is possible to mix ordered and unordered lists. The last character used determines the list's type.

Skriv Markup
* Item 1
** Sub-item 1.1
**# Sub-item 1.1.1
**# Sub-item 1.1.2
** Sub-item 1.2
*# Sub-item 1.3
* Item 2
Output
  • Item 1
    • Sub-item 1.1
      1. Sub-item 1.1.1
      2. Sub-item 1.1.2
    • Sub-item 1.2
    1. Sub-item 1.3
  • Item 2
HTML
<ul>
    <li>Item 1
        <ul>
            <li>Sub-item 1.1
                <ol>
                    <li>Sub-item 1.1.1</li>
                    <li>Sub-item 1.1.2</li>
                </ol>
            </li>
            <li>Sub-item 1.2</li>
        </ul>
        <ol>
            <li>Sub-item 2.2.1</li>
        </ol>
    </li>
    <li>Item 2</li>
</ul>

Links are explicitely defined using double-square brackets ([[ ]]). There must be at least the link destination, but it is also possible to define its title first, separated from the link address with a pipe character (|).

When no title is given, the address is used as the title, shorten to 40 characters.

By default, every outgoing links (those containing "://" or starting with "//") SHOULD be set with a target="_blank" and a rel="nofollow" attributes. This behaviour SHOULD be configurable.

Skriv Markup
[[/language/intro]]
[[http://www.site.com/very/long/long/looong/url/as/you/never/saw]]
[[Skriv Markup | http://markup.skriv.org]]
[[contact@skriv.org]]
[[Contact|contact@skriv.org]]
Output
HTML
<a href="/language/intro">/language/intro</a>
<a href="http://www.site.com/very/long/long/looong/url/as/you/never/saw"
   target="_blank" rel="nofollow">http://site.com/very/long/long/looon...</a>
<a href="http://markup.skriv.org" target="_blank" rel="nofollow">Skriv Markup</a>
<a href="mailto:contact@skriv.org">contact@skriv.org</a>
<a href="mailto:contact@skriv.org">Contact</a>
Reasoning

Square brackets are commonly used to represent some kind of reference (MediaWiki, Creole, Markdown, Asciidoc, DokuWiki, TWiki, MoinMoin, ...). They are doubled to follow the Skriv rationale.

When you read some text, the title of a link contains more direct information than its destination address. That's why the title is written first, before the address, when defined.

7. Images

Images' syntax follows the links' syntax. Double-curly brackets ({{ }}) are used instead of double-square brackets, to define the image location. An optional text can be set as the image alternative representation.

Skriv Markup
{{http://skriv.org/logo.png}}
{{Skriv logo|http://skriv.org/logo.png}}
HTML
<img src="http://skriv.org/logo.png" alt="http://skriv.org/logo.png" />
<img src="http://skriv.org/logo.png" alt="Skriv logo" />
Reasoning

Curly brackets are like square brackets, but with a more “artistic” shape. That's enough to distinguish images from regular links.

Double-curly brackets are already used by DokuWiki.

8. Tables

Skriv Markup helps you to create simple tables as quickly as possible. It is not intended to generate complex tables with merged cells.

Each table row starts with a cell delimiter. There is two kinds of cell delimiter: double-pipe (||) for normal cells, and double-exclamation marks (!!) for header cells. Every cell begins with a delimiter.

Skriv Markup
!! Header 1 !! Header 2
|| Cell 1   || Cell 2
|| Cell 3   || Cell 4
Output
Header 1 Header 2
Cell 1 Cell 2
Cell 3 Cell 4
HTML
<table>
    <tr>
        <th>Header 1</th>
        <th>Header 2</th>
    </tr>
    <tr>
        <td>Cell 1</td>
        <td>Cell 2</td>
    </tr>
    <tr>
        <td>Cell 3</td>
        <td>Cell 4</td>
    </tr>
</table>
Reasoning

The major goal with the table syntax was to provide a convenient way to create tables, without doing ascii-art. That's the reason why there is only two type of cells, no merged cells, and a very simple layout.

Pipes are the natural characters to create vertical separations between elements. It's perfect for table representation. Exclamation marks have a similar shape, with a subtle difference to indicate headers.

9. Horizontal rules

Horizontal rules are done by putting at least four minus signs on the same line, without anything else on the line. There must be no space before the minus signs.

Skriv Markup
----
Output

HTML
<hr />
Reasoning
The four minus signs markup represent a line, like an horizontal separator in the page. It is used by a lot of other systems (Creole, Markdown, reStructuredText, WikiWikiWeb, TWiki, ...).

10. Quotes

To write a quote, add a right angle bracket (>) at the beginning of each line. If you need many paragraphs inside the quote, just mark blank lines as well.

Skriv Markup
> Quotes use right angle brackets.
>
> Paragraphs are managed as usual.
> Line-breaks too.
Output

Quotes use right angle brackets.

Paragraphs are managed as usual.
Line-breaks too.

HTML
<blockquote>
    <p>
        Quotes use right angle brackets.
    </p>
    <p>
        Paragraphs are managed as usual.<br />
        Line-breaks too.
    </p>
</blockquote>
Reasoning
The right angle bracket character is a convenient mean to separate a quote from the rest of the text (already used in Markdown).

11. Footnotes

Footnotes are used to add internal links inside a document, referencing some chunks of text that should be listed at the bottom of the page.

They are defined using double-parenthesis ((( ))), where the footnote is referenced. Usually, footnotes are identified by an incremented number; if you want to use a label in place of that number, write it first, separated from the footnote's text by a pipe character (|).

Skriv Markup
Arthur C. Clarke is one of the best SF author ((just after Issac Asimov)).

The Ford T is the car of the century ((Source|ahead Mini and Citroën DS, see
[[Wikipedia|http://en.wikipedia.org/wiki/Car_of_the_Century]])), but everybody knows
it should be the VW Beetle (([[Wikipedia|
http://en.wikipedia.org/wiki/Volkswagen_Beetle]])).
Output

Arthur C. Clarke is one of the best SF author 1.

The Ford T is the car of the century Source, but everybody knows it should be the VW Beetle 3.

1. juste after Isaac Asimov

Source. ahead Mini and Citroën DS, see Wikipedia

3. Wikipedia

HTML
Arthur C. Clarke is one of the best SF author <sup><a href="#cite_note-1"
id="cite_ref-1">1</a></sup>.

The Ford T is the car of the century <sup><a href="#cite_note-2"
id="cite_ref-2">Source</a></sup>, but everybody knows it should be the VW Beetle
<sup><a href="#cite_note-3" id="cite_ref-3">3</a></sup>.
<div class="footnotes">
    <p class="footnote"><a href="cite_ref-1" id="cite_note-1">1</a>. juste after
 Isaac Asimov</p>
    <p class="footnote"><a href="cite_ref-2" id="cite_note-2">Source</a>. ahead Mini
 and Citroën DS, see <a href="http://en.wikipedia.org/wiki/Car_of_the_Century">Wiki
pedia</a></p>
    <p class="footnote"><a href="cite_ref-3" id="cite_note-3">3</a>. <a
 href="http://en.wikipedia.org/wiki/Volkswagen_Beetle">Wikipedia</a></p>
</div>
Reasoning

Parenthesis are used to write secondary content that it not crucial to the meaning of a text. Using double-parenthesis indicates that footnotes are like “tertiary content”, even less important so it can be put down at the end of the page.

Double-parenthesis are already used by DokuWiki.

12. Abbreviations

Abbreviations are written using double-question marks (??). The abbreviation and its explaination are separated by a pipe character (|).

Skriv Markup
??EFF|Electronic Frontier Foundation??
Output
EFF
HTML
<abbr title="Electronic Frontier foundation">EFF</abbr>
Reasoning
Question marks are the symbol for interrogation and help. The purpose of this markup is to provide some explaination about a term, so it fit very well.

13. Preformatted text

Preformatted texts are blocks of text rendered using monospace font. Line breaks are kept. Skriv syntax is still interpreted.

To create a preformatted text block, just at a space character at the beginning of each line of the block. In fact, once space is enough, but you can put as many spaces as you want.

Skriv Markup
 At least one space at the beginning of each
 line is enough to create a preformatted paragraph.
 
 Skriv syntax **works**.
Output
At least one space at the beginning of each
line is enough to create a preformatted paragraph.

Skriv syntax works.
HTML
<pre>
At least one space at the beginning of each
line is enough to create a preformatted paragraph.

Skriv syntax <strong>works</strong>.
</pre>
Reasoning

Adding space characters at the beginning of the line is the fastest way to define a style on a block of text. By indenting it from regular text, it gives a special meaning to the text.

MediaWiki already uses this writing to create preformatted text blocks.

14. Verbatim text

Verbatim text are preformatted text blocks without any interpretation. They are written using triple-square brackets ([[[ ]]]).

Skriv Markup
[[[
Triple square brackets also create
preformatted paragraphs.

**Skriv** syntax is __not__ interpreted.
]]]
Output
Triple square brackets also create
preformatted paragraphs.

**Skriv** syntax is __not__ interpreted.
HTML
<pre>
Triple square brackets also create
preformatted paragraphs.

**Skriv** syntax is __not__ interpreted.
</pre>
Reasoning
The angular shape of square bracket characters is a good reminder of verbatim texts' aspect (separate block, monospace font). The usage of opening and closing square brackets is perfect to mark the block's boundaries.

15. Code

As for verbatim text, Skriv syntax is not interpreted inside code blocks. The difference between a verbatim text block and a code block is the presence of the programming language's name after the three opening square brackets (there could be spaces between the brackets and the language's name, but it's not a mandatory).

Syntax highlighting is let to the interpreter will.

Skriv Markup
[[[ php
class Foo {
    public function show() {
        print("bar\n");
    }
}
]]]
Output
class Foo {
    public function show() {
        print("bar\n");
    }
}
HTML
<pre><code class="language-php">
class Foo {
    public function show() {
        print("bar\n");
    }
}
</code></pre>
Reasoning

Since code blocks content is not interpreted, they are only a special case of verbatim text blocks. So it's logical to keep usage of triple-square brackets.

Code blocks are rendered as a <code> inside a <pre> tag, because it's the recommended method in HTML 5. When syntax highlighting is activated, this markup is not a mandatory.

16. Styled paragraphs

This syntax is a convenient way to apply some CSS styles to paragraphs. Styled blocks are written between triple-curly brackets ({{{ }}}). All paragraphs inside will inherit the specified styles. CSS classes are typed just after the opening brackets.

It is possible to nest styled paragraphs. Just add triple-curly brackets-enclosed blocks inside existing ones. For a better readability, you can add any number of spaces and/or curly brackets before the CSS class names; the sole obligation is to start the lines with three opening curly brackets and three closing curly brackets.

Skriv Markup
{{{css_class1 css_class2
CSS classes apply to all paragraphs.

Whatever their ''number''.

{{{ {{{ css_class3
This paragraph has the **3 CSS classes**.
}}} }}}
}}}
HTML
<div class="css_class1 css_class2">
    <p>
        CSS classes apply to all paragraphs.
    </p>
    <p>
        Whatever their <em>number</em>.
    </p>
    <div class="css_class3">
        <p>
            This paragraph has the <strong>3 CSS classes</strong>.
        </p>
    </div>
</div>
Reasoning
Curly brackets are undeniably bound to CSS syntax. Every web developers have a mental connection between CSS instructions and curly brackets.

17. Smileys & Symbols

Skriv Markup provide helper scriptures, for adding special characters that are not easy to write with a regular keyboard. These characters are useful to add small illustrations to the text.

17.1 Smileys

:-) :-( :-D 😃 :-p 😋
:-| 😐 ;-) 😉 :-o 😲 :-x 😶
:'-( 😥 :-@ 😠 :-* 😘

17.2 Symbols

:sun: :cloud: :umbrella: :star:
:phone: :check: :mark: :cross:
:skull: :atom: :radioactive: :biohazard:
:moon: :square: :circle: :triangle:
:arrow: :arrowhead: :bullet: :love:
:heart: :spade: :diamond: :club:
:note: :recycle: :flag: :scale:
:warning: /!\ :peace: :yinyang:
:clock: :hourglass: :command: :enter:
:infinity:
:dice1: :dice2: :dice3: :dice4:
:dice5: :dice6:
:_1/2_: ½ :_1/3_: :_2/3_: :_1/4_: ¼
:_3/4_: ¾ :_1/5_: :_2/5_: :_3/5_:
:_4/5_:
:_1_: :_2_: :_3_: :_4_:
:_5_: :_6_: :_7_: :_8_:
:_9_: :_10_: :_11_: :_12_:
:_13_: :_14_: :_15_: :_16_:
:_17_: :_18_: :_19_: :_20_:
:_A_: :_B_: :_C_: :_D_:
:_E_: :_F_: :_G_: :_H_:
:_I_: :_J_: :_K_: :_L_:
:_M_: :_N_: :_O_: :_P_:
:_Q_: :_R_: :_S_: :_T_:
:_U_: :_V_: :_W_: :_X_:
:_Y_: :_Z_:

18. Extensions

Skriv Markup has an extension mechanism, designed to add new features to the language without modifying its basic syntax. Extensions may also be called “plugins”.

Extensions are validated before becoming a part of the official Skriv Markup syntax. Official extensions SHOULD be available in any Skriv Markup implementation, but they COULD be deactivated at will.
Unofficial extensions MAY be activated at will.

Look at the page about extensions to get the list of validated plugins.

18.1 Inline

Inline extensions are written using double-angle brackets (<< >>). The extension's name must be written just after the opening brackets. If the plugin needs some parameters, they are added just after, separated by pipe (|) characters.

Here is an example plugin, which goal is to insert the given number of “lorem ipsum” paragraphs.

Skriv Markup
<<lipsum|2>>
HTML
<p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque leo sem,
    commodo quis tempus luctus, tempor vel libero. Phasellus rutrum ipsum accumsan
    mauris gravida nec ultricies ante mattis. Ut et nibh neque.
</p>
<p>
    Praesent pulvinar rhoncus tincidunt. Ut eleifend sollicitudin nibh sed
    porttitor. In hac habitasse platea dictumst. Etiam bibendum mi id ligula
    blandit pulvinar et quis neque. Duis sagittis tempus tellus at rutrum.
</p>
Reasoning
Angle brackets are not used for any other element of the Skriv Markup syntax. However, they are immediately identified as special markup, because of their usage in HTML.

18.2 Block

Block extensions are very similar to inline ones. They are delimited by triple-angle brackets (<<< >>>), with the name and possible options just behind the opening brackets.

Here is an example plugin, which translates the given text. The first parameter is the input language, the second parameter is the output language.

Skriv Markup
<<<translate|french|english
écrire, travailler, organiser
>>>
HTML
<p>
    write, work, organize
</p>
Reasoning
Same reasoning than for inline extensions. Triple-characters are used for blocks as usual.