[Discuss] Definition lists

[bmorelli25]

Summary

(AsciiDoc - Description Lists)

For Asciidoc’s description list, we use MyST’s definition list. Note that this feature is not enabled by default and one needs to add deflist to myst_enable_extensions.

<term>
: <definition>
<term>
: <definition>

The Elastic Asciidoc engine defines multiple types of description lists which are formatted differently. The different types are specified by an attribute before the description list. For example, this specifies that the description list is of type ‘horizontal’:

[horizontal]
<term>:: <description>
<term>:: <description>

For now, they will all be converted as the standard MyST definition list.

To do

• Determine if Add initial support for structured settings references (yaml) #105 is a suitable replacement for definition lists
• Find any instances where this might not work as a replacement
• Update the migration tooling to convert d lists to yml
• Determine if we can use inline yml or if yml must be in an included file

[Mpdreamz]

The markdown library we use has optional support for definition lists in the following format:

https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/DefinitionListSpecs.md

Term 1
:   This is a definition item
    With a paragraph
    > This is a block quote

    - This is a list
    - with an item2

    ```java
    Test


    ```

What I really don't like is that this introduces space indentation sensitive formatting to the source documents for the benefit of the output.

If we can capture all valid use cases for this with more specific directives we will create a more prescriptive writing experience and a more uniform UX on the user facing docs.

[bmorelli25]

If we can capture all valid use cases for this with more specific directives we will create a more prescriptive writing experience and a more uniform UX on the user facing docs.

Added as a question to follow-up with during bug bash next week.

[Mpdreamz]

Given how pervasive definition lists are in docs openend:

#348

To add support for vertical definition lists.