Awesome.
Note1: single line blocks without params will look a bit strange:
...
!cut:
...
Question. What reasons were to use ruler-style separators to mark start/end? Seems i missed this discussion.
Note2: In serarator it’s better to avoid chars, used to mark fenced blocks. That will greately simplify seeking block end.
I was considering minimising lines by using !!! format, but you said it looks bit too much like ASCII. Also the reason for ruler-style seperators is to make it clear when the start and end is.
Also it makes for good fall back for code blocks directives e.g.
!asciiDiagram: width=100 height=100
```````````````````````````````````````````````````````
|\_/| **************************** (\_/)
/ @ @ \ * "Purrrfectly pleasant" * (='.'=)
( > º < ) * Poppy Prinz * (")_(")
`>>x<<´ * (pprinz@example.com) *
/ O \ ****************************
```````````````````````````````````````````````````````
looks like this, in an unsupported system (where no fenced block is supported), and for pandoc with fenced code support, it can recognize the box as a fenced code still. :
!asciiDiagram: width=100 height=100
|\_/| **************************** (\_/)
/ @ @ \ * "Purrrfectly pleasant" * (='.'=)
( > º < ) * Poppy Prinz * (")_(")
`>>x<<´ * (pprinz@example.com) *
/ O \ ****************************
For your cut example, would this format work? Single line directives is:
...
!extentionName param
...
Thus:
...
!cut
...
So in this context : means this is a multiline block. So lack of this, indicates it is a single line block.
Alternatively, we could just keep the same logic as above, but just make : an optional extra, for visual stylistic purpose.
In separator it’s better to avoid chars, used to mark fenced blocks.
What do you suggest?
note: first post updated.
For !cut it could be difficult to distinguish between inline and block. Right now no problem, but possible collisions in general case.
A block must be placed on the start of a line, and have a blank line on top.
This means, collision is only possible at the very first line of a paragraph, solvable via a space if want inline. Thus:
Block:
!cut this para
Inline
!cut this paraA have no best suggestions now. Still consider this as alternative:
!!:name optional params
...
!!
!css should be implemented using the {} attribute syntax. The rest looks nice.
I thinked a bit more. Visually, i like ```````````````````-style separators for multiline blocks. If we require, that end separator exactly match start, that should help to resolve possible conflicts with fences. Because blocks will require more backticks than fences.
But should we force user type such separators by spec? Can it become boring on practice?
Well that’s the idea behind giving people the flexibility of choosing how their fenced block may look like.
I did try thinking of what a “fenceless” paragraph look like, and it’s not that good. Plus it makes it hard to deal with multiline blocks like so:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
!extensionName:
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Thus by letting people define their own “fence character” for directives it would be more obvious, and would also drastically reduced chances of collision with other fenced syntaxes.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
!extensionName:
000000000000000000000000000000000000000000000000000000000000000000 {.style}
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
000000000000000000000000000000000000000000000000000000000000000000
!extensionName:
`````````````````````````````````````````````````````````````````` {.python}
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
``````````````````````````````````````````````````````````````````
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Perhaps we should amend the flexible fence concept, to allow for detection of “special blocks” (which I think lu_zero wanted in terms of the {} syntax) (And I think there is some others like pandoc YAML block --- , ...)
(Oh, and another thing added. The directive will ignore the ‘{}’ attribute in beginning of flexible syntax, for determine the flexible fence characters.)
!extensionName: param
< repeated sequence of character | or | Start block of a special markdown block > {#id .Style}
... content to read into !extensionName ...
< repeated sequence of character | or | End block of a special markdown block>
Allows for ::
|| Pandoc’s YAML --- , ... (Though I would say it’s better to just use --- ):
!YAML:
---
title: 'This is the title: it contains a colon'
name: Author One
affiliation: University of Somewhere
...
|| CSS/C/etc… {} style as proposed by lu_zero… doesn’t look good tho. And potentially dangerous) :
!css:
{
body {
overflow: hidden;
background: #000000;
}
}
Overall, the biggest pro for flexible fencing for directives is that leverage the commonmark fencing tradition of “repeated characters for start and end markers”, and has good collision resistance.
I’d restricted fensing char types to limited number. No need to make flexibility in places, where it’s not required. We need to provide something visually attractive and easy to type, but not unlimited ascii art.
Hmmmm… well I like the format. Would perhaps restricting to 3 types of fencing be okay, based on how we want it to behave when in an implementation that doesn’t recognize generic directives at all?
###Three types of fencing to support to ensure acceptable fallback:
(note: Please suggest other characters, if you like the concept, but not the fencing characters)
(1) Display as code block ( e.g. codes or ASCII art )
!python:
````````````````````` {.python}
print("Hello World")
`````````````````````
(2) Display as normal content ( e.g. spoilers ):
!spoiler:
!!!
harrys kills voltmort
But spares hermimi
!!!
(3) Hide block content from display ( e.g. settings or page declarations )
e.g.
!pandocStyleYAML:
---------------------
layout: resume
.....................
!jekellStyleYAML:
---------------------
layout: resume
---------------------
###Seems bit hard to do (2) … well what if…
(1) Display as code block ( e.g. codes or ASCII art )
`````````````````````!python {.python}
print("Hello World")
`````````````````````
(2) Display as normal content ( e.g. spoilers ):
!!!spoiler
harrys kills voltmort
But spares hermimi
!!!
(3) Hide block content from display ( e.g. settings or page declarations )
e.g.
---------------------!pandocStyleYAML
layout: resume
.....................
---------------------!jekellStyleYAML
layout: resume
---------------------
What’s your opinion? Can you provide a visual example of what you want? I can show how I see, but kind of hard to see your perspective. Perhaps show a few examples yourself as well.
!:cut
!:spoiler
content
```Or
!!:spoiler
content
!!
Admittedly your second example looks better (Since the : in first example make it look rather ugly). Though do we really need : ?
Shouldn’t this work just as well, and is more visually simple.
!!!spoiler
content
!!!
The concern about this approach however, is the fallback.
This is how your two examples will break here. Is any fine with you? :
(1) (added a !!! block example of similar style)
!:cut
!:spoiler
content
!:spoiler
!!!
content
!!!
(2) (added a code block example of similar style)
content
!!!:spoiler
content
!!!
Anyhow I hope somebody else add their opinion. I think I made my own preference pretty clear. Which is directive before fenced block without !:). But I would like to know if there is any other opinions besides mine and vitaly.
Kramdown has a neat syntax to add attributes to blocks
> A blockquote with a title
{:title="The blockquote title"}
{: #myid}
Or in general
this is a paragraph
with some lines
{: .spoiler}
Or
{: .spoiler}
this is a paragraph
with some lines
Yes, I still like this syntax for block directives as well:
!!!name
content
!!!
or for that matter:
@@@name
content
@@@
with optional [label](arg){#myId .myClass key=val key2="val 2"} like:
@@@asciiDiagram[_lovely_ cat]{ width=100 }
|\_/|
/ @ @ \
( > º < )
`>>x<<´
/ O \
@@@
Maybe separating spaces should be allowed for block directives: [] () {}
The body/content for block directives could be optional as well, so this:
@@@youtube[Funny video](dQw4w9WgXcQ)
renders as:
<figure>
<iframe width="420" height="315" src="//www.youtube.com/embed/dQw4w9WgXcQ" frameborder="0" allowfullscreen></iframe>
<figcaption>Funny video</figcaption>
</figure>
while this:
see @wikipedia[Foobar]
renders as:
<p>
see <a href="https://en.wikipedia.org/wiki/Foobar">Foobar</a>
</p>
And as @lu_zero mentioned, for simple cases attributes added to existing elements already suffice (see the proposed attribute syntax).
Btw shouldn’t we keep to consistent attributes like this? I remember that for blocks in general, the {} goes at the last line. Thus for your ascii cat example:
!!!asciiDiagram: _lovely_ cat
|\_/|
/ @ @ \
( > º < )
`>>x<<´
/ O \
!!!
{ width=100 }
Also about your choice of @. Isn’t it already used by most commenter as a signifier for usernames? e.g. twitter uses it as username, discourse uses it for username as well.
Fenced code blocks in Pandoc, MarkdownExtra and Kramdown (and therefore the consistent attributes proposal) have the attributes on the first line. It’s kind of nice to see all the arguments/attributes before you start to read the code/directive content…
``` {.language-ruby}
x = 1
```
True, but shouldn’t be a problem with @@@name or when the [] in @name[] is mandatory.
It’s kind of nice to see all the arguments/attributes before you start to read the code/directive content…
Alright
@@@name is ugly, and people would hate to have to type that for usernames.
@name[] is ugly. What if people want to call directive without arguments. E.g. @TableOfContents or !cut etc…
Using ! is much safer, and is internally consistent, since is already used to embed images. So naturally
!name[]() would imply special embedded content/declaration.
yeah, on the other hand @name kind of looks more special, extension-like than !name… I would like to hear how other people feel about this…
Btw I’ve been thinking about the issue of the !cut example. As in how do you distingush between a single line inline directive vs block directive. Here is an example of the issue.
!cut "this is settings for a block directive, but how do you know that `!cut` is not inline?"
!cut this is a normal paragraph with `!cut` as an inline directive in the first line.
I think the solution is to use : as the block directive switch. This is since anything after : in a block directive is purely arguments for the directive only. Thus
!cut: "much clearer that this is for the `!cut` directive"
!cut this is a normal paragraph with `!cut` as an inline directive in the first line.
Unfortunately, this does mean that the block directive for !cut without argument is
!cut:
But I think that is a suitable compromise.