Block Directives

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.

Hmmm…

  • 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(intro.md)

  • Generating QR codes !QRcode[google](www.google.com)

  • 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…

2 Likes

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}
content
:::  

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

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

tagName::::::::::
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.

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.
2 Likes

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

Personally, i like this one:

:::name params
content
:::

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

@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
:::
content
:::

!name: param
content

!name: param

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

example 2 (vitaly’s preference)

:::name params
content
:::

example 2 (From mb21’s post)

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

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

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.

As I understand this proposal, it is for a generic block syntax. But how would it be rendered in practice? For example, does this Markdown:

:::
Text inside block here
::: 

produce this HTML?

<div>
Test inside block here
</div>

As mentioned in the spoiler topic, the use of div is discouraged even in HTML. It might be better to default the block to render an HTML element that contains semantic meaning within a passage of text. Such as the <aside> element:

The aside element represents a section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content. Such sections are often represented as sidebars in printed typography.

Out of the box, they might produce an HTML div, but the main use would be to allow users to write filters that do custom things with groups of block elements.

1 Like

I would keep intact all unmatched things. That includes:

  • blocks without type (name)
  • blocks with unsupported types

Reason: plain div is useless, not well seen in previews/result and can confuse user with disappearing of :::.

But i’m not sure that it’s possible to do such rollback for all cases. If not - then “default” rendering layout should be used, styled with warning.

This markup is not to create div, it’s to create any custom sublayout, defined by block name.

tl;dr: If no extensionName found, check if it is a whitelisted html tag, else fall back as div with classname named as extentionName

aye, and plus it’s probably safer if we do not automatically associate extension name as HTML tag names.

Instead we could just make a recommendation for there to be a list where certain extension names will correspond to a simple extension for inserting that HTML tag.

Thus

:::::::::::::: details {.classname} ::::::::::::

 :::: summary {.classname2} ::::::::::::::::::::
 This is summarized content of this document
 :::::::::::::::::::::::::::::::::::::::::::::::

real content here

:::::::::::::::::::::::::::::::::::::::::::::::

simply passes though as

<details>
<summary>This is summarized content of this document</summary>
<p>real content here</p>
</details>

Where details and summary tag passthough extension is located in a “simpleExt.yml” file or something like that. (And maybe a default white list of commonly used HTML tags)

If no full extension is found, and no html pass through is associated, then it will fall back to div with the extension name being a CSS name.

e.g. warning is not an extention, and is not a known html tag thus:

:::::::::: WARNING ::::::::::::::
warning message located here
:::::::::::::::::::::::::::::::::

<div class="warning" > warning message located here </div>

Btw, just noticed. Can you allow for single space indent of the container and fence, to mean the same thing? I noticed the summery tag looks bit hard to located without the slight indent.


###edit: ooops… I read the last few messages incorrectly… well my point should still stand

to answer that question, it does seem that the “aside” tag would be a good choice, as a default for unnamed block content. Since a fenced : does imply that it is a boxed content, that is set aside from the main content.

How would the feature be communicated to causal writers? The descriptions so far are quite technical.

1 Like

It’s the falling back mechanism that is complex. Writing it on the other hand is not that complicated.

So in terms of communications, just have examples for most commonly used extensions.

For the rest, just have a page detailing the general container, and then a list of community known and supported extension “man pages” ( covering, input arguments supported, and content type and examples )

Any preliminary ideas? Or you don’t like fenced containers at all?

::: reminds me a little of rst,

the kramdown extension markup is a little more flexible:

{::comment}
This text is completely ignored by kramdown - a comment in the text.
{:/comment}

Do you see {::comment}this text{:/comment}?
{::comment}some other comment{:/}

{::options key="val" /}

And might be used in a quite flexible way.