Block Directives

Extensions
62

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" }
63

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

64

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

65

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.

66

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
67

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.

68

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.

69

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.

70

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