Description Lists

A description list is a pattern where a term is followed by a description. HTML supports this pattern with three tags: dl, dt, and dd, respectively. The description list (dl) wraps around the term and description, or multiple pairs like an ordered or unordered list (ol, ul) wraps around list items (li).

Note: Not until a few days after I started this draft did I find out that these lists are called Description Lists, and not Definition Lists, per HTML specs. I think this is news to other Homebrewery developers, as well, since they are described as Definition Lists everywhere in codebases and conversations. I’m going to consciously try to change my brain, starting with this post.

Syntax

In the above example you can see a set of inline descriptions inside one description list, followed by a multi-line description where a single term has multiple descriptions.

You can actually skip the empty line between terms if you plan to only use inline terms/descriptions, and they’ll get packed into the same parent dl with a minor change in the default styling applied. More on that later.

Styling

By default there isn’t much going on with styling for these lists, but there is one invisible bit: the hanging indents. If long enough to wrap to the next line, an inline description will be indented from the left a bit so that the term hangs over. This is also true of multi-line definitions, with the simple difference of it starting on the next line below the term and being entirely indented. This is handy for places where you might want to make it easier to scan for keywords.

If you want to distinguish the term from the description visually, you can go a few routes. In Homebrewery’s default PHB theme you can see a description list if you drop in a monster stat block snippet. This

The “Armor Class … Speed” section, and the “Condition Immunities … Challenge” section both use these lists. The additional bold styling comes from just applying strong syntax around the terms, for example: **Speed**.

If you just looked at the Preview pane, though, you might actually see more description lists than are actually used. “Onion Stench”, “Sassiness”, “Hangriness” are all *terms* that are being defined in a very structured manner. Same goes for “Open Chin Choke” and “Team Elbow”. So why aren’t those setup as definition lists?

Well, basically it boiled down to clarity for users– the defining characteristic of description lists that we wanted to emphasize was the hanging indent, and to avoid adding two different style declarations that exist solely inside of the monster stat block and then requiring additional div containers for applying classes, we just went with wrapping the terms in asterisks to bold them.

Perhaps an alternative would be:

This isn’t a perfect solution, though. As of this writing, the inner text contents of a dd tag are not wrapped in <p> paragraph tags. This means that if you have multiple paragraphs inside a single description, the line break is only a line break (<br>), and not actually indicative of multiple paragraphs, and you don’t get the paragraph indent on paragraphs after the first. This is reflected in the “Hangriness” description, which is two paragraphs.

Regardless, the above example shows that you can style the term or the description independently, and if you wrap your description lists in regular div blocks ({{... }}) and give them custom class names you can start to customize them individually wherever you use them in your document.

Closing Thoughts

I actually learned some new things with this post, both about descriptions lists (beyond their correct name) and regular lists (ol/ul). I’m hopeful that in the future we can make some changes:

• Regular lists (ol/ul) wrap their inner content in <p> tags, and we should apply that to description lists, too
• With regular lists, you can create multiple paragraph elements inside a list by matching their indentation to the initial paragraph start for that list item, shown below in the second bullet point. We should do the same with description lists. Requiring this “indentation matching” would make the next point possible, I think.

• Regular lists don’t require empty lines between items, and description lists shouldn’t either. Currently it’s possible to keep inline description list items all in one list without having empty lines, but multi-line descriptions require that break, or they don’t know when to end. But if multi-lines instead required their new-lines to be indented to match their initial sibling, we could likely remove the need to have an blank line.
• Regular lists have a parent element, ul/ol, and then a single child element for each bit of information, li. Description lists have the parent dl but two child elements for each bit of information, dt and dd. This makes it more difficult to style the sets as sets, and is a reason why we default to definition lists always having empty lines between each term– because every dt/dd is it’s own list dl, we can target those dls as if they were li elements…but it’s not semantically correct. And it’s odd.

Anyway, those are just gripes for now.