A block directive allows for embedding or calling certain operations that does not require extending the core syntax.
(Note: There is a debate between ! vs @ as generic directive indicator. I prefer ! as it indicates embedded content or intent.)
Block Syntax
Block syntax, using repeated sequence as delineators. !!! & the code fence syntax is used to indicate if content should be treated as normal text or code blocks if no extension found. (Could also indicate to extension on the type of fencing used, might be useful)
Single Line/Leaf Block Directive
!extensionName: param
{#id .Style key=value}
Multiline/Container Block Directive
Fenced
Standard
(single space between !extensionName: and param)
!extensionName: param
< commonmark fencing start>
... content to read into !extensionName ...
< commonmark fencing end>
{#id .Style key=value}
e.g.
!extensionName: param
::::::::::::::::::::::::::::::::::::::::::::
... content to read into !extensionName ...
::::::::::::::::::::::::::::::::::::::::::::
compact mode
(no space after !extensionName:)
!extensionName:< commonmark fencing start>
... content to read into !extensionName ...
< commonmark fencing end>
{#id .Style key=value}
e.g.
!extensionName::::::::::::::::::::::::::::::
... content to read into !extensionName ...
::::::::::::::::::::::::::::::::::::::::::::
!extensionName:`````````````````````````````
... content to read into !extensionName ...
````````````````````````````````````````````
No Fence (For single paragraph content)
!extensionName: param
... content to be...
... read into !extensionName ...
... falling back as normal content if failed...
Some other paragraph that is not read into !extentionName
This also allows for content that falls back as code block (Good for ASCII art)
!extensionName: param
... this is code and it's content to be...
... read into !extensionName ...
... falling back as code block if failed...
Some other paragraph that is not read into !extentionName
HTML examples
standard directive
!extensionName: param
::: {#id .Style key=value}
... content to read into !extensionName ...
:::
falls back on missing directive as
<extensionName id="id" class="class" key=value >
... content to read into !extensionName ...
</extensionName>
code fenced directive
!extensionName: param
``` {#id .Style key=value}
... content to read into !extensionName ...
```
falls back on missing directive as
< extensionName id="id" class="class" key=value >
<code> ... content to read into !extensionName ... </code>
</extensionName>
##Directive example:
... paragraph ...
!cut:
... paragraph ...
!youtube: _VHfymfJCXs
... paragraph ...
!css: show=hide
`````````````````````
// ... insert css layout code that can be applied to this document..
// ... only if the site or program actually is willing to use it...
`````````````````````
!eval: python package=mathPy
`````````````````````````````` {.python}
# the {.python} doesn't get counted into the pattern recognition
# of end of declaration block, because either parser is smart enough to ignore {}
# or it recognizes... well somehow. I'm sure there is a way to make it work
print("hello world")
``````````````````````````````
!metadata: display
---
CommonMark: 0.1.23-github.username.projectname
title: Title for the top bar of any browser
layout: report
***
##Presentation Examples:
!graph: type="pie chart" inputType=csv x=Year y=Price
`````````````````````
Year,Make,Model,Description,Price
1997,Ford,E350,"ac, abs, moon",3000.00
1999,Chevy,"Venture ""Extended Edition""","",4900.00
1999,Chevy,"Venture ""Extended Edition, Very Large""",,5000.00
`````````````````````
!asciiDiagram: width=100 height=100
```````````````````````````````````````````````````````
|\_/| **************************** (\_/)
/ @ @ \ * "Purrrfectly pleasant" * (='.'=)
( > Âș < ) * Poppy Prinz * (")_(")
`>>x<<ÂŽ * (pprinz@example.com) *
/ O \ ****************************
```````````````````````````````````````````````````````
!asciiDiagram: width=100 height=100
|\_/| **************************** (\_/)
/ @ @ \ * "Purrrfectly pleasant" * (='.'=)
( > Âș < ) * Poppy Prinz * (")_(")
`>>x<<ÂŽ * (pprinz@example.com) *
/ O \ ****************************
!spoilers:
Snaper kills Dumton
In Harry's Plot
This is good for large block of spoilers
##Single Line:
Though, if itâs a single line, wouldnât it be easier to just use inline directives?
!spoiler: harrys kills voltmort
##Multiline:
!spoiler:
:::
harrys kills voltmort
But spares hermimi
:::
Implement some form of block directive in your implementation? Note it down here!
http://www.reddit.com/r/LightWeightMarkup/wiki/commonmark/unofficialextensions
Some ideas for generic directive extensions plugins: