Markdown Format Extension - BlueFeather Manual

BlueFeather Manual

# Markdown Format Extension

BlueFeather has imported some extensions addition to the original Markdown syntax.

- From PHP Markdown Extra
  - Definition List (dl)
  - Footnote
  - Header-id attribute
  - Fenced Code Block
  - Table
  - Difference from PHP Markdown Extra
- BlueFeather Original
  - TOC
  - Block Separator

## From PHP Markdown Extra

- If you want to know about original PHP Markdown Extra, see the http://michelf.com/projects/php-markdown/extra/.

### Definition List (dl)

Pair of a term and a sentence which starts with `:` symbol is parsed as Definition List.

    Mandarin
    : Orange and sweet-sour.

    Apple
    : Red and sweet.

> Mandarin
>   Orange and sweet-sour.
> Apple
>   Red and sweet.

You can use multiple terms, multiple sentences, or both.

    Mandarin
    : Orange.
    : Sweet-sour.

    Apple
    Ringo
    : Red and sweet.

> Mandarin
>   Orange.
>   Sweet-sour.
> Apple
> Ringo
>   Red and sweet.

And that, you can make sentences a paragraph element by blank-line, and you can append any block-level elements after the paragraph by indent.

    Mandarin

    : Orange and sweet-sour. Used for juice.

    Apple

    : Has these features.

        * Sweet
        * Red and globular

> Mandarin

>   Orange and sweet-sour. Used for juice.

> Apple

>   Has these features.

>   - Sweet
>   - Red and globular

### Footnote

Such as that text, parsed as footnote.

    That's some text with a footnote.[^1]

    [^1]: And that's the footnote.

> That's some text with a footnote.[1]

Definition of footnote can be in any places.

And that, instead of number, any ids.

    That's some text with a footnote.[^ex-fn]

    [^ex-fn]: And that's the footnote.

### Header-id attribute

You can add header-id attribute.

    Recipe {#recipe}
    ----

    See the section of [Recipe](#recipe).

    ## Recipe ## {#recipe}
    ----

    See the section of [Recipe](#recipe).

> ## Recipe

> See the section of Recipe.

Be careful, any character except line-break (LF) is NOT allowed after id.

### Fenced Code Block

    ~~~
     A range from a line which starts with three or more tildes (~) to another
    line same as it is parsed as code-block.
    ~~~

>     A range from a line which starts with three or more tildes (~) to another
>     line same as it is parsed as code-block.

### Table

Cells separated pipe-symbol ( `|` ) are parsed as table. 1st line is headers. 2nd line is separators. And 3rd or later line is data.

    |Name    |Color      |Number|

    fcfd1dbc26fe1eb65b18b627e8ea89e8

> Name | Color | Number
> --- | --- | ---
> Apple | Red | 8
> Mandarin | Orange | 32

Right borders and spaces is optional.

    |Name    |Color      |Number

    fcfd1dbc26fe1eb65b18b627e8ea89e8

    bf9ccdcc0cb9c1c670dad6cbca029ad5

But, be careful, left borders is NOT optional. This behavior differs from PHP Markdown Extra.

If a colon ( `:` ) is at right of cell in 2nd line, the column is right-aligned. If colons are at left and right, the column is center-aligned.

    |Name    |Color      |Number|

    694e324b969d76dea39a1c14c8d6fe79

> Name | Color | Number
> --- | --- | ---
> Apple | Red | 8
> Mandarin | Orange | 32

### Difference from PHP Markdown Extra

- At PHP Markdown Extra, a block-level html tag can be indented. But, at BlueFeather, a block-level html tag CANNOT be indented. (same as original Markdown)

- PHP Markdown Extra doesn't emphasize this phrase.

      Please open the folder "secret_magic_box".

  But, BlueFeather emphasizes this phrase in this case. (same as original Markdown)

- BlueFeather doesn't parse Markdown Inside HTML Blocks and Abbreviations.

- Left borders of table is NOT optional.

## BlueFeather Original

### TOC

`{toc}` at line head is substituted table of contents. (a list of headers)

    {toc}

> - From PHP Markdown Extra
>   - Definition List (dl)
>   - Footnote
>   - Header-id attribute
>   - Fenced Code Block
>   - Table
>   - Difference from PHP Markdown Extra
> - BlueFeather Original
>   - TOC
>   - Block Separator

You can specify to include levels of header.

    {toc:h3..}

> - Definition List (dl)
> - Footnote
> - Header-id attribute
> - Fenced Code Block
> - Table
> - Difference from PHP Markdown Extra
> - TOC
> - Block Separator

Default is h2 - h6.

Following formats are usable to specify levels.

    {toc:h3-}    (same as previous example)
    {toc:h3}     (h3 only)
    {toc:h3..h4} (from h3 to h4)
    {toc:..h4}   (from h2 to h4)

Be careful, Headers written by Markdown on the document root, are only included in TOC. So following headers are NOT included in TOC.

    <h2>not included</h2>

    > ## not included ##

### Block Separator

Normally, two or more block-level elements (lists, code blocks, or others) are combined even if a blank line splits them. But, the specification is bad in that case.

    1. list1 item1
    2. list1 item2
    3. list1 item3

    1. list2 item1
    2. list2 item2
    3. list2 item3

    <ol>
    <li>list1 item1</li>
    <li>list1 item2</li>
    <li><p>list1 item3</p></li>
    <li><p>list2 item1</p></li>
    <li>list2 item2</li>
    <li>list2 item3</li>
    </ol>

One way for the matter, to use horizontal line.

    1. list1 item1
    2. list1 item2
    3. list1 item3

    ----

    1. list2 item1
    2. list2 item2
    3. list2 item3

    <ol>
    <li>list1 item1</li>
    <li>list1 item2</li>
    <li>list1 item3</li>
    </ol>

    <hr />

    <ol>
    <li>list2 item1</li>
    <li>list2 item2</li>
    <li>list2 item3</li>
    </ol>

But, you might not want horizontal line in some cases. Because of the matter, at BlueFeather, only one tilde symbol works as block separator.

    ~

For example:

    1. list1 item1
    2. list1 item2
    3. list1 item3

    ~

    1. list2 item1
    2. list2 item2
    3. list2 item3

    <ol>
    <li>list1 item1</li>
    <li>list1 item2</li>
    <li>list1 item3</li>
    </ol>

    <ol>
    <li>list2 item1</li>
    <li>list2 item2</li>
    <li>list2 item3</li>
    </ol>

1. And that's the footnote. ↩