Pyrone markup language for writing articles

## Pyrone text markup language (for articles)

Pyrone uses Markdown-based markup language, it supports complete core Markdown elements set and some additional features.
Please consult official Markdown syntax documentation for complete language reference. In paragraphs below we are describing most used language construction.

## Basic markup

Use an empty line to split text into separate paragraphs, each paragraph consists of non-empty text lines.

    Just write text, insert line breaks
    to format it appropriately.
    This is still the same paragraph.

    And this is a new one.

    And another. Remember: the empty line creates paragraphs.

You can also create headers, to do so just prepend a line with some #-characters, one # stands for the top-level header with largest text, ## stands for second-level header etc up to six #-s. There is an also alternative way to create headers, just underscore the line with some “=” or “-” charecters to create 1st and 2nd level headers correspondingly.

    # This is the largest-font header

    And this is the 1st level header too
    ====================================

    And 2nd level
    -------------

    ###### This is the smallest possible header

Inline text formattin is easy: enclose text in *-s to create *emphasized* text and in double *-s **strong** text. Emphasized text is displayed as italic, and strong as an embolden text. And of course there is an alternatives: enclose phrase in underscores to create emphasized, and use triple *-s to create ***strong emphasis***.

    The next word is *emphasized*, and this **a strong text**.
    Strong ***emphasis***.

Lists are also easy, put each list item on separate line and prepend it with *, to create sublists place an indent before the *.
In order to insert monospaced font (for inline code samples for example) use backticks (`), like this ``$x = sort($list);``. If the code contains backtick then enclose it with two backticks and so on: ```$x = `ls`;```.

    * first list item
    * second, and the next items are indented
        * these are
        * sublist items
    * and continue the main list

Ordered lists are also simple:

    1. First list item;
    1. Second
        * nested
        * unordered
        * list

Hypelinks are bit tricky, pyrone intentionally doesn't parse URL-like character sequences and doesn't automatically transform them into the links. So you need to explicitly mark URLs: this text, for example, <https://github.com/sigsergv/pyrone> will be converted to clickable hyperlink https://github.com/sigsergv/pyrone. Email addresses also processed in similar way: <sergei@regolit.com> will be converted to mailto-hyperlink sergei@regolit.com.

    Visit google website <http://google.com> to search
    internet about markdown.

You can use customized hyperlinks, see below an example, it will be displayed as Google:

    [Google](http://google.com)

It's possible to insert inline images, to do so use the following code, it will show the image :

    ![alt text](http://example.com/static/images/sample-image.png)

Quotation, just put character `>` at the beginning of first line of block that needs to be rendered as quoatation.

    > This is a quitation.
    It could be multiline.
    >
    > And even multi-paragraph!

## Extended markup

Extended markup is not a part of original markdown specs so the code below has to be used in pyrone only.

### Images from pyrone storage

Pyrone has its own file storage and you can use pictures stored there in your articles, syntax code for that is very similar to one that is used for inserting external images:

    This is a picture named `file-name.jpg` from internal storage:

    !![alt text](file-name.jpg)

If that image in the storage is too large you can display instead reduced-size picture, it's also a hyperlink that opens an original picture (we added `/m` suffix to picture name):

    !![alt text](file-name.jpg/m)

### HTML elements attributes

It's possible to set custom html elements attributes, it's required sometimes to finely tune generated HTML code, for example, you can insert inline images (that are float in the text) using this code:

    ![ALT-TEXT{@style=float:left;}](http://example.com/image/url.png)

it will add additional attribute `style="float:left;"` to generated HTML element IMG.

### Footnotes

You can insert footnotes with hyperlinks, so if you want to create footnote, place footnote marker `[^fn-1]` in the text (you can use any characters instead of `fn-1`, numbers, for example) and place footnote content somewhere in the article (at the very end of it for example):

    Footnotes look nice[^fn-1], but unfortunately they break
    attention focus[^fn-2].

    [^fn-1]: So cute tiny hyperlinks!
    [^fn-2]: You need to read text somewhere else and then return to main
    text flow. So this footnotes block will be rendered after the article, and
    numbered hyperlinks are placed in the main text.

### Definition lists

Inspired by HTML elements <DL>, <DD> and <DT>:

    **First term**
    :   defintion data

    **Multiline**
    :   Multiline defintion lines
        are possible, just prepend
        lines with 4 spaces

    Plain term (not strong)
    :   And its definition

will be rendered into the following HTML:

    <dl>
    <dt><strong>First term</strong></dt>
    <dd>defintion data</dd>

    <dt><strong></strong></dt>
    <dd>Multiline defintion lines
    are possible, just prepend lines
    with 4 spaces</dd>

    <dt>Plain term (not strong)</dt>
    <dd>And its definition</dd>
    </dl>

### Coloured code

This construction will generate block coloured as C++ source code, line `:::cpp` specifies source code language and won't be include in the resulting html code.

    ~~~~~
    :::cpp
    for (int x=0; x<666; ++x) {
        z();
    }
    ~~~~~

Here is the resulting output:

    for (int x=0; x<666; ++x) {
        z();
    }

If you don't specify source code language the code block will be displayed as regular code block without any source language guesses.
You can also render code with line numbers, to do that put the following construction as the first line of code (instead of `cpp` you can use another language): `#!cpp`.

    ~~~~~
    #!cpp
    // the line above will not be rendered
    for (int x=0; x<666; ++x) {
        z();
    }
    ~~~~~

### Splitting long articles

You can split large article into two parts using construction <cut>. After rendering only the text before <cut> (“preview”) will be displayed in the articles list and after that preview hyperlink pointing to complete article will be place.

    This is a short article description.

    <cut>

    And this is a remaining part of the article.