Definitions

[leebyron]

This borrows the syntax from a few other markdown extensions for definition lists (<dl>).

Term
: Definition

I've also come up with a variation on that (which as far as I can tell is novel) to allow for a definition within a phrase. That seems surprisingly common in other specs (The whatwg URL spec uses this pattern pervasively - example)

:: Definition of a *term*.

The formatting of these is pretty lightweight. They just get indented and italicized, similar to grammar definitions.

Defined terms can also be reference linked elsewhere by italicizing a case-insensitive string match:

In any paragraph, just reference a *term* to create a definition link.

[leebyron]

@benjie - this is along the lines of what I was referring to in graphql/graphql-spec#846

A full Appendix glossary isn't being auto generated, but they are getting added to the Index at the bottom of the page. My thought is that we could start by using this syntax to ensure terms are getting defined in context throughout the doc, and then determine if an additional Appendix is necessary or if the index links are sufficient

[benjie]

I’m concerned that this seems to rely on a single newline and may have issues with prettier when proseWrap: always is enabled. I have not tested these concerns yet (am on mobile).

I think the plan of defining terms in place and later considering adding a term index is sensible.

[benjie]

Maybe the standalone definitions could use :: as the prefix to make them unambiguous with respect to whitespace.

[leebyron]

Double line breaks should be significant and not replaced by prettier, right? What are some test cases you're worried about? I can add them in the suite to avoid ambiguity

[leebyron]

For standalone definition paragraphs, they need to be at the beginning of a block (not directly following another paragraph line)

Prev paragraph

: Definition of *term*

Prettier should never collapse this double newline.

Is the potential failure concern that prettier would collapse this:

Term
: Definition

To this:?

Term : Definition

[leebyron]

proseWrap: always does in fact collapse the line

I know some other markdown extensions allow line breaks between the term and the definition, e.g.:

Term

: Definition

And perhaps the :: for standalone definition paragraphs would disambiguate

[leebyron]

Updated to allow empty lines between definitions (kramdown, and others that support this syntax also allow that) and adopting your idea to use :: for paragraph definitions to disambiguate.

[benjie]

Yeah, exactly. Sorry for the lack of detail, you can imagine writing precise whitespace on mobile would be quite a pain! You figured out my meaning, and I think the :: solution is relatively obvious 👍

I've scanned over the test document and the behaviours expressed therein are in line with what I would expect (with the possible exception of :: *just a term*, but honestly I'm on the fence about what to do with that so am fine with the status quo).

If this can wait until the weekend I can hopefully give it a proper test/review, but if you're keen to get it out feel free 👍

[benjie]

Oh! One critical thing: you have A _Term_ can use either \* or \_ italics. for referencing a term, but we'd also need this for defining the term since prettier replaces * with _ when defining italics in general. Might want to add a couple test cases for this.

[leebyron]

Great call out - that is handled by the parser but there was not a test case - fixed!

I'm considering opening an issue on prettier for the proseWrap: always collapsing definitions. While it's not part of the core commonmark (neither are tables!) it is a syntax used by many extended markdown specs

[leebyron]

Issue filed: prettier/prettier#10701