Reduce the need to use blank lines to indicate markdown text

[damithc]

Current:

<box>
**abc**
</box>

→ renders as **abc**

<box>

**abc**
</box>

→ renders as abc

Can we get the content in <box> component (and other similar components) to be parsed as Markdown by default, without needing to add a blank line or a <markdown> tag? Is there any downside to considering everything as markdown?

[yamgent]

Is there any downside to considering everything as markdown?

The only downside I can think of is that it would no longer be Markdown compliant, because the standard explicitly states that all content inside HTML tags must be treated as normal text, unless a blank line is added.

Markdown compliance might be important, if we expect authors to copy and adapt Markdown content from other sources.

[Chng-Zhi-Xuan]

Agree with @yamgent. If blank lines want to be explicitly avoided, you can always use the <markdown> tag. Although markdown content cannot be indented for a consistent look.

<box>
  <markdown>
**abc**
  </markdown>
</box>

[damithc]

The only downside I can think of is that it would no longer be Markdown compliant, because the standard explicitly states that all content inside HTML tags must be treated as normal text, unless a blank line is added.

Oh, I didn't know about that. in that case it is fine. But didn't we encounter a case where such a blank line would mess up the rendering? #352

[yamgent]

But didn't we encounter a case where such a blank line would mess up the rendering? #352

Yes, that's because the blank line also allows Markdown parsers to determine where the HTML blocks end.

The example linked in issue 352 shows an example of how the <pre> didn't get nested correctly because the end of the HTML block is determined differently. The problem faced in #352 is that nested HTML tags can produce weird/unexpected results.

So the blank line sort of "plays" multiple different roles in the Markdown specs.

[damithc]

I see. Is there any advice we can give users on this regard? Or any other thing we can do to improve the situation?

[yamgent]

Is there any advice we can give users on this regard? Or any other thing we can do to improve the situation?

We can write down the blank line behaviour in our documentation, and possibly mention the nested tags scenario, so that authors are more aware of this behaviour. Though it may become quite technical, and authors might end up doing trial and error anyway, but still worth mentioning.

Our documentation already mentions the <markdown> tags in "Content Authoring", so that should be fine.

Jekyll (which uses a different markdown library kramdown), allow authors to specify that the content inside is in markdown without having to use a blank line with markdown="1":

<div markdown="1">
This content is written in _markdown_
</div>

[damithc]

Jekyll (which uses a different markdown library kramdown), allow authors to specify that the content inside is in markdown without having to use a blank line with markdown="1":

<div markdown="1">
This content is written in _markdown_
</div>

Can/should we do something similar?

[yamgent]

Doesn't seem to have any difference in functionality, compared to what we already have though:

<div><markdown>
Some **bold** text here.
</markdown></div>

[damithc]

Doesn't seem to have any difference in functionality, compared to what we already have though:

Slightly more readable, for example, the two <div> tags line up.

<div markdown>
Some **bold** text here.
</div>

In cases where nested tags are involved (which is where the problem happens), one more pair of tags can make a significant difference in readability?

The only downside I can think of is that it would no longer be Markdown compliant, because the standard explicitly states that all content inside HTML tags must be treated as normal text, unless a blank line is added.

Does this apply to our own tags such as <panel>?

[yamgent]

Slightly more readable, for example, the two <div> tags line up.

<div markdown>
Some **bold** text here.
</div>

In cases where nested tags are involved (which is where the problem happens), one more pair of tags can make a significant difference in readability?

I guess it does save spaces, and also reduce some typing at the same time. I am open with introducing such a keyword.

Does this apply to our own tags such as <panel>?

Yes, that fits with the 7th condition in the specs.

[damithc]

Let's put on hold for now. Not a high priority.

[jovyntls]

Hi Prof @damithc , is this feature (having a markdown keyword such as <div markdown></div> to reduce the need for blank lines) still something that you'd like? Should we remove the s.OnHold tag?

[damithc]

@jovyntls It is still not a high priority but if it can be done easily, we can go ahead. Also wondering if the keyword should be markdown or markbind (or both).

[jovyntls]

Also wondering if the keyword should be markdown or markbind (or both).

I think we could stick to one keyword, in case users have the misconception that there could be different behaviours for different keywords.

Pros of using markdown:

• Better consistency with existing keywords, especially if the functionality is identical to our existing <markdown></markdown> tag.
• Possibly less confusing for users since we can avoid introducing new keywords (afaik currently markbind is not used anywhere in our Markbind syntax)

Cons of using markdown:

• It's not exactly pure markdown since our Markbind components will be parsed as well 🤔 Could this confuse users?

[damithc]

I'm OK with using markdown

[ang-zeyu]

Agree with having <div markdown></div> in general, but it is hard as <div>s can contain not just markdown (e.g. panels, etc.).

The current <markdown/md> rendering happens in a second pass, which is simple, but makes stateful features unusable (e.g. footnotes relying on an earlier definition), and places a restriction that the content inside must be fairly simple markdown only. (else we risk rendering markdown twice which is undefined)

Ideally the markdown renderer should be altered to treat <div markdown></div> more "naturally". (that needs to be researched ~heavily~ very heavily and defined..)