Modify Markdown dl syntax to support multiple subsequent dt or dd elements

[develleoper]

Description

The current <dl> syntax (i.e. dt :: dd) only supports a 1:1 ratio of terms to descriptions.

Reference

• Original Discussion at Reddit
• The following examples follow the syntax set forth in Kramdown, Pandoc, MultiMarkdown, and Markdown Extra.

Basic Case:

First term
: First description
: Second description

<dl>
  <dt>First term</dt>
  <dd>First description</dd>
  <dd>Second description</dd>
</dl>

[develleoper]

Advanced Cases:

Preceding paragraph

First term
Second term
: Description, first paragraph
  Description, second paragraph
  - Description, unordered list item
  > Description, block quote

Following paragraph

<p>Preceding paragraph</p>
<dl>
  <dt>First term</dt>
  <dt>Second Term</dt>
  <dd>
    <p>Description, first paragraph</p>
    <p>Description, second paragraph</p>
    <ul>
      <li>Description, unordered list item</li>
    </ul>
    <blockquote>Description, block quote</blockquote>
  </dd>
</dl>
<p>Following paragraph</p>

[calculuschild]

What would you see this be displayed as when entered into the Homebrewery? Any particular style/format from the D&D books that a multi-dd would be used for?

[ericscheid]

Two paragraphs in a <dd>, from #181

Two paragraphs in a definition of a term, from #181.

Though this is arguably an edge case, I am however all for semantic coding — it's a rising tide that raises all boats.

[develleoper]

@ericscheid I believe the ticket and associated pull request actually use bold tags and paragraphs to accomplish that? Is this incorrect?

@calculuschild honestly, there's nothing here we can't reproduce via bold tags and default paragraph indents (or just manually writing one's own <dl> tags); but I do think that the image shared by @ericscheid is one good example of its potential use-case, and the emerged standard used across the other various markdown implementations provides a more succinct and consistent syntax. Personally, in development work, I often use them for elements with one header and multiple inline values, like the lists of skills and equipment which classes choose from at level 1, but I acknowledge in that case it's much, much simpler to just use a single paragraph. I'll try to sort out my thoughts on use case.

[calculuschild]

Two paragraphs in a

, from #181

This is already handled naturally by just using normal paragraphs, since we don't use dd in that part of the stat block.

@develleoper One issue we had in the original version of the Homebrewery was over-use of obscure syntax combinations to activate different features (two <hr> next to a blockquote would appear as a stat block, code blocks using backticks being invisible and used for column breaks, etc. It got really easy to write bad code that led to lots of user error, and we also very quickly ran out of enough syntax to do everything we wanted. The V3 renderer was an attempt to clear out a lot of "unused" syntax to make room for cleaner stuff. For instance we don't use blockquotes > at all in V3 because they were obnoxious to type out and we could get the variety needed just from CSS classes.

So, we're open to adding syntax for stuff, but we do want to make sure it has a clear utility that isn't already covered by other syntax. It's nice to have some syntax (like multi-dd) left as a backup for some future element we haven't accounted for yet. We also don't want multiple syntaxes that do the same thing if we can help it. Once a syntax is out on the site, even if we don't give it any special styling and it just appears as a standard paragraph, that locks us out of using it in the future for something more specialized. For example if you are using it just for equipment lists that appear as a standard paragraph anyway, and we change it to appear more as a big blocky stylized box, suddenly all of your brews that relied on the previous appearance will be broken.

[ericscheid]

This is already handled naturally by just using normal paragraphs, since we don't use dd in that part of the stat block.

This works because those dd in that theme are styled the same as normal paragraphs. This is a workaround.

This works because that list action names and their respective definitions are styled using paragraphs to look like a definition list. This is a workaround.

If however there was another theme that said "definition lists look like this [whatever]" (including multi-paragraph dd) then the user would need to come up with a different workaround. Changing themes shouldn't require hacking the brew.markdown just for styling reasons — this is why emitting semantic html is useful.

Perhaps @develleoper could work up a PR which merges all three options:

a simple one-line syntax for one-definition terms:

term :: defn

multiple definition terms:

term::
: defn
: defn2

indented definitions to support complex definitions

term::
: defn
  another paragraph
  - bullet item
  - bullet 2

For the latter two cases (if possible due to parsing logic) make the :: optional.

[calculuschild]

This works because those dd in that theme are styled the same as normal paragraphs. This is a workaround.

There are literallly no definition list present in that part of the statblock. It's not merely a workaround that styles dd to look like a paragraph. We really do just use bold text and normal paragraphs:

[ericscheid]

Yes, sorry, that's what I meant: the "bit of text that is a definition in a list".

Which is a p masquerading as a dd.

[develleoper]

@calculuschild Yeah, I noticed that the current implementation just uses bold tags and paragraph breaks, and honestly, that is good enough for users to reproduce 5e styles.

I totally understand the battle against syntax bloat, I'm just advocating for altering the current (unused?) <dl> support to better comply with the rest of the industry's syntax and to allow for better support of the HTML spec on this tag. The tag is already in the system, it just doesn't support the full feature set that it could, and uses its own unique syntax apart from the one on which other parsers seem to have standardized.

And @ericscheid, I don't want to jump the gun, but will happily work up a PR, if that's acceptable.

[calculuschild]

@develleoper

The current single-line dl syntax is indeed used in multiple places already on the Homebrewery, so we can't eliminate it entirely without breaking existing documents. In fact, it was a deliberate choice to break from the other syntax because the occurences where we use DL only require a single dt and dd; the term :: definition allows the Markdown to be clean-looking in a single line.

Again, we welcome the new syntax (and an accompanying PR), but we would want to have a clear decided use for it. We don't want users to rely on it only to be surprised later on when we finally figure out a use case and start adding styling.

a p masquerading as a dd.

@ericscheid I see your point, but I would argue that this specific example is not really a Term with two definitions. The second paragraph is part of the same definition. So it's still a single term, single definition, but we would be hijacking multiple dds to artificially split the definition into paragraphs, which is not really semantically correct either. (For what its worth, I personally I still think this example is semantically closer to a paragraph than a definition list anyway.)

Regardless, while I agree semantic HTML is good, I suggest that avoiding syntax bloat is more important if the output is visually identical. I am not keen to confuse users by making Stat blocks into a weird outlier that uses a whole different syntax where everywhere else a paragraph would do the same thing.

Tldr; if we add a new syntax, it should do something we can't easily do already. Add features, not duplicate features, if that makes sense.

[ericscheid]

Yes, it is a term with one definition with two paragraphs — which is part of the proposal.

It would be written as:

term
: paragraph one
  paragraph two, on a new line, indented

[develleoper]

@calculuschild yeah, that totally makes sense. I'm curious why the decision was made to support <dl> tags in a one-off way that folks familiar with markdown would not expect, but I respect that y'all have valid reasons, and am mostly just eager to help the parser support both.

I apologize for the lack of clear use-case, and am still pondering that

[develleoper]

also apologies for the accidentally closed issue, my cat stepped on my touch pad and hit "close with comment" 🤦‍♀️😼

[ericscheid]

I'm curious why the decision was made to support <dl> tags in a one-off way that folks familiar with markdown would not expect

See PR here: 64d133f

The dl extension was added as part of the overhaul of transforming the mess of Legacy formatting to the new V3 formatting (we used things like "a bullet list following a horizontal rule will get formatted as X" to do monster stat blocks).

IIRC, at the time there was no clear markdown-community consensus on how to do definition lists, and Marked didn't have much guidance. We rolled with a simple syntax that worked for the immediate need.

That extension was added in July 2021. The use of that syntax for monster actions was added in Sep 2021 (i.e. the use case in #181 wasn't considered in July)

[calculuschild]

That sounds about right. I'll add that I think we may have been "inspired" by the

term
: definition

syntax somewhere along the way, since we ended up using colons as well. I suspect the reasoning for coming up with our own syntax was something like, "DL syntax isn't in any official specs, and is only a custom extension in a couple of Markdown parsers. Let's tweak it a bit to fit into one line since we will only ever use a single term and definition anyway."

Since Markdown is meant to be "as readable as possible... publishable as-is, as plain text" , the single-line DL we came up with seemed to match our actual output appearance in a way that remained legible, better than breaking the DL across multiple lines:

**Armor Class**
: 20 (chain mail, shield)

**Hit Points**
: 100(1d4 + 5)

**Speed**
: 47ft.

vs

**Armor Class** :: 20 (chain mail, shield)
**Hit Points**  :: 100(1d4 + 5)
**Speed**       :: 47ft.

although I think technically both syntaxes should be able to coexist without interference.

[develleoper]

Oh! That actually makes a lot of sense, and I find myself agreeing with regard to legibility of the code for this purpose. Thank you for the context!

[5e-Cleric]

This should be fixed with #3129