Block Directives

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.

For comparison (using http://talk.commonmark.org/t/generic-directives-plugins-syntax as reference )

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

Do you see ::comment[ this text ]?
::comment[ some other comment ]

::options{ key="val" }

Using my concept:

!comment::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
This text is completely ignored by kramdown - a comment in the text.
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Do you see !comment[ this text ]?
!comment[ some other comment ]

!options{ key="val" }

: can be changed to another symbol.

Example from kramdown does not allow content indentation, liked by some writers. And i’m not sure that it’s possible to make markup good for blocks and inlines in the same time. That’s why this topic was created separately.

:: should be changed since it is commonly used as namespace marker and that might or might not clash. @ had been considered and discarded since it used in @user and such.

{: and {:: are almost safe. and probably also !name[...]{} might be easy to parse.

Here an example

sphinx

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring

using the !name notation

!py:function[send_message(sender, recipient, message_body, [priority=1])]::
    Send a message to recipient
::
{param=str name=sender desc="The person sending the message"}
{param=str ....

This does not look that nice and would require the implementation to not collapse the key-value attribute attached to nodes but keep a a key-list_of_values.

Probably if I want to keep my sanity while I’m trying to support this sphinx feature might be just better do something like

!sphinx::
.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
::  

or use {::sphinx} and {:/} using the kramdown syntax.

I’m looking into sphinx + markdown since it would be something the rust people are also evaluating the mix.

using the indent-block syntax it would have the neat feature of degrade nicely on parsers not supporting it:

:: extension

    this is a part of the extension

    this as well

    :: options might be freeform strings
    :: or be=otherwise key=value 

Would render as

:: extension

this is a part of the extension

this as well

:: options might be freeform strings
:: or be=otherwise key=value

it would reuse the same logic used by the code and would be mainly compatible with rst.

:: py:function[send_message(sender, recipient, message_body, [priority=1])]

    Send a message to a recipient

    :: param str sender: The person sending the message
    :: param str recipient: The recipient of the message
    :: param str message_body: The body of the message
    :: param priority: The priority of the message, can be a number 1-5
    :: type priority: integer or None
    :: return: the message id
    :: rtype: int
    :: raises ValueError: if the message_body exceeds 160 characters
    :: raises TypeError: if the message_body is not a basestring

That’s all was discussed in spoiler thread. Indented markup is nice, but hard to use without appropriate editor (to quote blocks, for example).

There are people, who like it, and who dislike it. That’s personal and can’t be changed. I think, good spec should cover both styles, with single universal, or with 2 separate markups.

PS. may be fenced containers are not the best, but those allows to use both styles.

I’m more concerned about how attributes are used in rst and to make sure to match sphinx I won’t have to do something terrible.

having a rst-compatible support for block and span directives would be a huge plus for me.

Just noticed that @vitaly 's https://markdown-it.github.io/ demo contains custom containers. Glad to see that it it works well at the very least as a container format. Degrades rather gracefully as well. Great work!

Would be interesting to see how people find containers, and if it causes any problem. Also if it’s possible to use it as a container for latex maths or something like that.


:::: warning ::::
*here be dragons*
:::::::::::::::::

Degrades to :::: warning :::: here be dragons ::::::::::::::::: in common-mark strict mode. Else it uses warning as the classname to wrap around the *here be dragon* content.

It is not rst compatible and readthedocs does need something like the one I suggested to win more users to the markdown flavour.