Block Directives


I see. What about people doing the insane thing and using !!!!!! as a divider:

 Can you handle this now? Hahaha
    What did you expect? :D

or even:


          ! WARNING !
 Can you handle this now? Hahaha
    What did you expect? :D



I don’t like idea to add [](){} into spec for blocks. Looks like attempt to invent something universal with inlines without real needs. If you go this way, you can get html-like result in the end - working, but overcomplicated and not relevant to initial goal.

May be, {} only, but also under question.

That can work, but require parser to know exactly if named block is leaf or container. Because blocks can be nested. If you change parser to another one, that don’t know some named block directives, nesting sequence will become broken.

1 Like


I’m not sure I understand. The point of my proposal is exactly to avoid this. Therefore a leaf block is !!!name on one line, while a container block has an opening !!!name and a closing !!!. You agree that there should be a different syntax for leaf and container block directives, right?

The [inline content] (argument) {key-value pairs} serves simply as a common way to supply the directive with these three things, which I think is equally useful for inline and block directives. I’m thinking of what kind of AST a custom filter or module would like to receive after a markdown parser has parsed the document. An AST that contains something like:

  - name: String
  - parsedInlineContent: InlineBlocks
  - unparsedInlineContent: String
  - arg: String
  - attributes: Map(String, String)

Examples use cases for [](){} in Leaf Block Directives:

  • @@@youtube[title of *funny* video](09jf3ow9jfw)

  • @@@video[title](filename.mp4){width=400}

  • @@@snip[label](path/to/code.scala)

  • @@@include(

  • @@@toc[*My* Contents]

It’s crossed my mind that :: might also be a suitable replacement for the @ or !.


::name[optional inline content](optional arg){optional key-value pairs}

Leaf Block:

:::name [optional inline content] (optional arg) {optional key-value pairs}

Container Block:

:::name [optional inline content] (optional arg) {optional key-value pairs}
further block content
1 Like


Sorry, i’ve mistyped. I wished to say that, that there should be way to differ one line and multilline block directives.

1 Like


@mofosyne I’ve looked at your updated first post in this topic. If I understand correctly, our two proposals are fairly close and there are mainly two things separating them:

  1. Mine fails if we would allow the [](){} stuff to spread over multiple lines (as I proposed in the attributes thread…)
  2. Yours doesn’t have a way to specify InlineContent, i.e. the [] in my proposal.


Mine fails if we would allow the {} stuff to spread over multiple lines (as I proposed in the attributes thread…)

Well, now that I’ve been practising typing the {} syntax (via examples above). I’m incline to agree with vitaly that param should be more flexible. Since the {} is not very friendly for touch typing, and is only used in inline typing as a necessity.

Plus mine is still in keeping with the consistent attribute syntax. Since I recognize that a block can be styled via {} at the end, or at the fence start. I intentionally allowed two formats, because for short settings, the compact block directive is more intuitive. While for larger directive with more complex params, it should really be in it’s own line for legibility.

I encourage you to type typing my two forms and your form. You’ll see the difference I noticed.

Yours doesn’t have a way to specify InlineContent, i.e. the [] in my proposal.

Well that’s because I don’t think it comes under the jurisdiction of generic block directives. I have no issue with your inlinecontent proposal, but’s not a generic directive. It’s more related to the family of [](){}, though I do not have a name for it.

I’m okay with it.

blababba [ inline content ]{.style} blabalba

I think it comes under Content Block/Inline Syntax

(tl;dr: I support it, but think it needs to be in a different category. Not a directive.)
(Oh and btw, this is a block directive thread. So limited scope of discussion here)



Actually, I’m out of ideas too. It may be that this feature is more advanced than is actually needed for practical purposes.

In programming, good libraries and frameworks often come out of real world projects, rather than being designed in isolation. A pattern might be repeated a few times in different projects before being moved into a library. I think we should use the same approach when deciding whether to just use HTML or to invent new Markdown syntax.



Well if anything I don’t commonmark to be a programming language. I rather it be more like CSS, which is more declarative.

There is one thing I am annoyed in CSS however. It’s a lack of constants support (e.g. #define in C).

And yea I agree, that’s why I would like to see it in action in something like @vitaly 's remarkable parser, his is a good candidate as it is designed to be pluggable from the ground up. Seeing it in action might help us iron out some real world issues in terms of the syntax. But of course, only one style could really be tested at a time, so he would need to choose one of our proposals (or make one up himself).



I think we need to resort cases why do we need block directives. Because part of examples intersects with fenced blocks.

IMHO, cases are:

  1. Multiline presentation blocks, when content can have markdown. Example - spoiler.
  2. Single line blocks. Example - cut

Everything else can be covered with fenced blocks and don’t need this extention.




  • Creating form inputs: Introducing markdown extensions for form input

  • Generating plots and bargraphs, etc… !plot( y=3x+2 )

  • Dynamically Updated Table of Contents !TOC

  • Embedding video !youtube[ cats ]

  • Metadata

  • Printing page directives (e.g. splitting pages) !pagesplit

  • Generating output from a code snippet !eval( print "hello world")

  • Evaluating a maths input !calc[ 1+1= ]

  • Generating a table from remote source !table(data.csv)

  • Including external commonmark files (e.g. compiling a book or report) !include(

  • Generating QR codes !QRcode[google](

  • Including the first generic clipart found: !clipart[ cat dancing ]( optional image url )

  • Image macro generator (Very useful for sight impaired readers):
    !imagemacro[Of all the front yards in all the world][The cat walks into mine](Noir Dog)

  • Css overrides (block example): !css: .underline{ text-decoration: underline; }

  • Text To Speech section: !speak[ I **stress** that you should really follow the following diagrams shown below ]{ pointToID="#diagram" }

  • In a slideshow, these text is hidden from view, but is spoken out loud. Can view speech in transcription window.

  • In html view, it is shown as a collated transcription under each header. Expandable as needed, with maybe a button to listen.

  • In print view, it is seen as a speech box.

  • This is good when writing educational material, e.g. lecturers.

  • Document declaration (block directive) !CommonMark::

    !CommonMark: 0.1.23-github.username.projectname
    Title: Title for the top bar of any browser
    Date: 32-4-2002

  • etc…



Massive +1 on using ::: - I find the !!! and @@@ etc. really distracting.

I think aesthetics are really important here.



Interesting aaren. Well would this work for you?

!blockextention: arg

... content for block extension


This ties into my proposal to use !extensionname format. What separates block from inline is :

Note: my block directive format is different from mb21’s proposal.

I read elsewhere here, that ::: is best used as a block alternative to [ ]{} like:


... div container ...

::: { #id .style key=value }

edit: modified top post to match

1 Like


I’m more in favour of @mb21’s proposal for container blocks, i.e.

:::name[arg]{#id .class key=value}

But I can see the merit of !name[arg]{} for inline elements (rather than ::name[arg]{}) - it’s one less character and it sits well with the existing image syntax.

I’m not as bothered by consistency as I am by visual impact: I don’t want container blocks to be shouting at me :smiley: and I’d like the arguments to be on the same line as the fence.

1 Like

The case for a `<!CommonMark>` declaration tag

In this thread I think that we could have a compact version of ::: that can deal with any <tagName>. e.g.

content here

So perhaps we could also offer a compact version of block directives like

!extensionName[arg](arg):::::::::::: { #id .style key=value }
This is extension content. 

I think some of the issue in this thread discussion, is that some of us want to have a compact notation, while others want legibility. I think this form might help with getting both legibility, while being compact still.


Lists without a list indicator character?

I have some room in my brain to start thinking on blocks implementation in remarkable. Since my efforts are limited with js only, i need to know first:

  1. Will it make sense for someone here? Will js implementation solve your problems or you need parser in differend language?
  2. Can we focus on fenced-style blocks now? If fenced-style containers added, will it solve some of your problems or it will be useless without other things?

Why i’m asking:

  • Someone can need block containers before spec complete. Fenced-style container blocks seems to be not conflicting with spec, and have a good chance to appear in final spec (extensions) with minimal changes. Discussing other cases will take much more time.
  • I don’t like to push anyone with my implementation. If nobody interested in js version OR not need fenced style blocks - then i should not disturb community with my problems. I will participate in spec discussion anyway, but will remove arguments caused by timelines and particular implementation.


Can anyone summarize the most wanted syntax for fenced block containers?

Personally, i like this one:

:::name params

As discussed in What could a “spoiler tag” extension look like? , fenced-like principle is good for such blocks. But fence spec says, we should not use backtick on the same string. If we proparate rule to “: should not be used”, collision with params syntax possible.

1 Like

No-markdown islands

@vitaly . I prefer (example 1), and it’s single paragraph compact form. since you can more easily see what extension is being used, and all of it’s settings. (example 2 and 3 may get cutoff in smaller screen, when reading it as a text file)

Plus, @vitaly, don’t you agree that my proposal is easier to parse, since you don’t have to look backwards? (plus, adding a word after a fence opening, is typically semantic for “classname”)

So in summary of wanted syntax:

summary of most wanted syntax

example 1 (my preference)

!name: param

!name: param

!name: param

can have []{} but that is dependent on each extension.

example 2 (vitaly’s preference)

:::name params

example 2 (From mb21’s post)

:::name [params] {key=val}

::::: name [params] {key=val} :::::


Parse efforts will be similar. Example of (1) takes too many space IMHO.

Do i understand right, that all wish to use : in marker?

1 Like


aye for fenced : as the marker here.



+++ Vitaly Puzrin [Nov 30 14 09:11 ]:

Parse efforts will be similar. Example of (1) takes too many space IMHO.

Do i understand right, that all wish to use : in marker?

I am undecided as yet.