Make fenced_divs extension more consistent with Markdown Directive Syntax

Make fenced_divs extension more consistent with Markdown Directive Syntax

[Benjamin Bray]

[-- Attachment #1.1: Type: text/plain, Size: 6286 bytes --]

(duplicated from pandoc#7480 on GitHub 
<https://github.com/jgm/pandoc/issues/7480> at the request of jgm)

I'd like to collect feedback on a backwards-compatible change to the 
fenced_divs extension which will make it more compatible with Markdown 
Directive Syntax.  Please let me know if you think this is a good idea, or 
if it might have any unintended consequences.

*Pandoc's fenced_divs Extension*

Pandoc's fenced_div extension 
<https://pandoc.org/MANUAL.html#divs-and-spans> currently supports the 
following syntax for creating divs:

Example 1 (try pandoc 
<https://pandoc.org/try/?text=%3A%3A%3A%3A%3A+%7B%23special+.sidebar+key%3Dvalue%7D%0AHere+is+a+paragraph.%0A%0AAnd+another.%0A%3A%3A%3A%3A%3A&from=markdown&to=html5&standalone=0>
)
::::: {#special .sidebar key=value}
Here is a paragraph.
And another.
::::: 

<div id="special" class="sidebar" data-key="value">
<p>Here is a paragraph.</p>
<p>And another.</p>
</div> 

Example 2 (try pandoc 
<https://pandoc.org/try/?text=%3A%3A%3A+Warning+%3A%3A%3A%3A%3A%3A%0AThis+is+a+warning.%0A%0A%3A%3A%3A+Danger%0AThis+is+a+warning+within+a+warning.%0A%3A%3A%3A%0A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A%3A&from=markdown&to=html5&standalone=0>
)
::: Warning ::::::
This is a warning.
::: Danger
This is a warning within a warning.
:::
:::::::::::::::::: 

<div class="Warning">
<p>This is a warning.</p>
<div class="Danger">
<p>This is a warning within a warning.</p>
</div>
</div>

*Limitations of fenced_divs / Proposed Behavior*

Strangely, Pandoc does not allow you to combine the two fenced_div syntax 
styles:
:::: container {.theorem #id key=value} ::::::
This is a theorem.
:::: 

<p>:::: container {.theorem #mytheorem key=value} :::::: This is a theorem. 
::::</p> 

I think this is a perfectly natural thing to do. Personally, I like to use 
this syntax when "container" is a common class that will be matched by CSS, 
and .theorem / .lemma / .corollary / etc are secondary classes that 
determine the contents of a ::before element (for instance).

Given the current behavior, I would expect the output to be something like 
this:
<div id="mytheorem" class="container theorem" data-key="value">
<p>This is a theorem.</p>
</div> 

*Proposed Implementation*

Here's a simple rewrite (see benrbray@8a20611 
<https://github.com/benrbray/pandoc/commit/8a20611e904487a61bcdf92a6a60ee83ca7929c7>) 
of the divFenced parser that allows for the proposed change. Seems to work 
locally and all tests currently pass.  I can make a PR if this is a 
desirable change. Some guidance on code style and how to write appropriate 
tests for this would be helpful. Thanks!

divFenced :: PandocMonad m => MarkdownParser m (F Blocks)
divFenced = do
  guardEnabled Ext_fenced_divs
  try $ do
    string ":::"
    skipMany (char ':')
    skipMany spaceChar

    -- begin change
    name <- option [] $ pure <$> (many1Char nonspaceChar)
    skipMany spaceChar
    (ident, classes, keyval) <- option nullAttr attributes
    let attribs = (ident, name ++ classes, keyval)
    guard (attribs /= nullAttr)
    -- end change

    skipMany spaceChar
    skipMany (char ':')
    blankline
    updateState $ \st ->
      st{ stateFencedDivLevel = stateFencedDivLevel st + 1 }
    bs <- mconcat <$> manyTill block divFenceEnd
    updateState $ \st ->
      st{ stateFencedDivLevel = stateFencedDivLevel st - 1 }
    return $ B.divWith attribs <$> bs

Background:  Markdown Directive Syntax

Some markdown implementations support the following de-facto standard for 
directive syntax 
<https://talk.commonmark.org/t/generic-directives-plugins-syntax/444>, with 
syntax for inline, leaf, and block directives. Perhaps in a future proposal 
it would be desirable to add these to the Pandoc AST for further 
processing, but for now I would be satisfied if the syntax for 
the fenced_div extension were updated to more closely align with the 
directive syntax.

Inline Directive
:name[content]{#id .class1 .class2 key=val} 

Leaf Directive
:: name [content] {key=val} 

Block Directive
::: name [inline-content] {key=val}
contents, which are sometimes further block elements
::: 

*Alternatives*
   
   - Instead of modifying the behavior of fenced_divs, create a separate 
   extension directive_divs
   - Incorporate Markdown directive syntax into the pandoc AST instead of 
   converting to divs (this would be a much larger change -- maybe more 
   appropriate for a future PR if this one is merged)
   - Re-write any directive syntax in my markdown documents to use the 
   format expected by pandoc (quite undesirable)

*Questions*

   - What do you think of this behavior?
   - Will this have any unintended consequences?
   - Has the adoption of directive syntax in Pandoc been discussed before / 
   any conclusions reached?
   - This proposal leaves out the "inline content" section of the markdown 
   directive syntax.  It could be easily included, but it's not obvious where 
   it should go (an attribute? a span?).  Perhaps it's more appropriate to 
   save for a later date if Pandoc ever properly adopts directive syntax.

*References*

Directive Syntax

   - Talk.CommonMark, "Generic directives/plugins syntax" 
   <https://talk.commonmark.org/t/generic-directives-plugins-syntax/444>
   - RemarkJS, remark-directive plugin 
   <https://github.com/remarkjs/remark-directive>
   - markdown-it, markdown-it-directive plugin 
   <https://github.com/hilookas/markdown-it-directive>

Possibly Related Issues

   - GitHub, Make fenced_divs more consistent with Markdown Directive 
   Syntax #7480 <https://github.com/jgm/pandoc/issues/7480>
   - GitHub, Documentation: Clarify fenced_divs #4037 
   <https://github.com/jgm/pandoc/issues/4037>
   - pandoc-discuss, New extension generic directives 
   <https://groups.google.com/g/pandoc-discuss/c/t953HXdjs7w/m/nROsXw7WBwAJ>

Thank you for your consideration!

- Ben

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/633f1aff-afa3-4191-8b69-909efa1ab5cen%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 10987 bytes --]