Here is the official core of Skriv Markup's syntax.
The Skriv Markup syntax' current version is alpha.
All special characters are escaped. For instance, less-than (<), greatear-than (>) and ampersand (&) characters are transformed during HTML export (respectively to <, > and &).
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.
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 ''
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.
Here is the first paragraph. With two lines. Here is the second paragraph, with many carriage-returns.
Here is the first paragraph.
With two lines.
Here is the second paragraph, with
many
carriage-returns.
<p>
Here is the first paragraph.<br />
With two lines.
</p>
<p>
Here is the second paragraph, with<br />
many<br />
carriage-returns.
</p>
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.
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.
works on**ly on full** words
two ''single quotes'' for italic
two <em>single quotes</em> for italic
two **asterisks** for bold
two <strong>asterisks</strong> for bold
two __underscores__ for underline
two <u>underscores</u> for underline
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.
two --minus signs-- for striking out
two <s>minus signs</s> for striking out
two ##hash signs## for monospace
two <tt>hash signs</tt> for monospace
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.
two ^^caret characters^^ for exponent
two <sup>cart characters</sup> for exponent
Caret characters are like little arrowheads indicating upside direction.
This syntax is already used by Creole.
two ,,commas,, for subscript
two <sub>commas</sub> for subscript
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.
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.
=Level 1 heading == Level 2 heading== ===Level 3 heading === ==== Level 4 heading
<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>
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.
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.
===Darth Vador ===Darth Vador=== ===Darth Vador===your father =Darth Vador \= your father =Darth Vador = your father=
<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>
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.
* Item 1 * Item 2 ** Sub-item 2.1 ** Sub-item 2.2 *** Sub-item 2.2.1
<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>
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.
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.
# Item 1 # Item 2 ## Sub-item 2.1 ## Sub-item 2.2 ### Sub-item 2.2.1
<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>
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.
It is possible to mix ordered and unordered lists. The last character used determines the list's type.
* 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
<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.
[[/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]]
<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>
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.
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.
{{http://skriv.org/logo.png}}
{{Skriv logo|http://skriv.org/logo.png}}
<img src="http://skriv.org/logo.png" alt="http://skriv.org/logo.png" /> <img src="http://skriv.org/logo.png" alt="Skriv logo" />
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.
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.
!! Header 1 !! Header 2 || Cell 1 || Cell 2 || Cell 3 || Cell 4
| Header 1 | Header 2 |
|---|---|
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |
<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>
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.
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.
----
<hr />
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.
> Quotes use right angle brackets. > > Paragraphs are managed as usual. > Line-breaks too.
Quotes use right angle brackets.
Paragraphs are managed as usual.
Line-breaks too.
<blockquote>
<p>
Quotes use right angle brackets.
</p>
<p>
Paragraphs are managed as usual.<br />
Line-breaks too.
</p>
</blockquote>
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 (|).
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]])).
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.
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>
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.
Abbreviations are written using double-question marks (??). The abbreviation and its explaination are separated by a pipe character (|).
??EFF|Electronic Frontier Foundation??
<abbr title="Electronic Frontier foundation">EFF</abbr>
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 add 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.
At least one space at the beginning of each line is enough to create a preformatted paragraph. Skriv syntax **works**.
At least one space at the beginning of each line is enough to create a preformatted paragraph. Skriv syntax works.
<pre> At least one space at the beginning of each line is enough to create a preformatted paragraph. Skriv syntax <strong>works</strong>. </pre>
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.
Verbatim text are preformatted text blocks without any interpretation. They are written using triple-square brackets ([[[ ]]]).
[[[ Triple square brackets also create preformatted paragraphs. **Skriv** syntax is __not__ interpreted. ]]]
Triple square brackets also create preformatted paragraphs. **Skriv** syntax is __not__ interpreted.
<pre> Triple square brackets also create preformatted paragraphs. **Skriv** syntax is __not__ interpreted. </pre>
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.
[[[ php
class Foo {
public function show() {
print("bar\n");
}
}
]]]
class Foo {
public function show() {
print("bar\n");
}
}<pre><code class="language-php">
class Foo {
public function show() {
print("bar\n");
}
}
</code></pre>
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.
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.
{{{css_class1 css_class2
CSS classes apply to all paragraphs.
Whatever their ''number''.
{{{ {{{ css_class3
This paragraph has the **3 CSS classes**.
}}} }}}
}}}
<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>
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.
| :-) | ☺ | :-( | ☹ | :-D | 😃 | :-p | 😋 |
| :-| | 😐 | ;-) | 😉 | :-o | 😲 | :-x | 😶 |
| :'-( | 😥 | :-@ | 😠 | :-* | 😘 | ||
| :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_: | Ⓩ | ||||
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.
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.
<<lipsum|2>>
<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>
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.
<<<translate|french|english écrire, travailler, organiser >>>
<p>
write, work, organize
</p>