Definition Lists

Definition lists are also supported in Markua. Definition lists are related to lists, but they are neither flat, simple nor complex. Instead, they are what they are: definition lists.

To define a definition list in Markua, use the following syntax:

term 1
: definition 1

term 2
: definition 2

There can be one to three spaces after the colon, or one tab.

A definition list can provide multiple definitions for a term:

term 1
: definition 1a
: definition 1b

term 2
: definition 2

A single term definition list is a definition list, regardless of how many definitions for the term exist:

term
: definition

Finally, like list items in complex lists, each definition list item can contain newlines and multiple paragraphs. What you do here is indent the subsequent lines by the same amount of space as the initial line. (If you do not indent the subsequent lines, then you’re ending the definition list and just starting a new paragraph.) As with list items, one newline is a forced line break; two newlines is a new paragraph:

You can nest resources inside a definition list. You cannot nest definition lists inside definition list items, however–that would be highly confusing.

Here's a paragraph before the definition list.

one
: This is the first definition of one. It's one paragraph.
: This is the second definition of one. It's two paragraphs.

  This is a second paragraph in the second definition of one.

two
: The second definition list item is simple.

three
: The third definition list item has three paragraphs.
  This is definition still part of the first paragraph.

  Here's the second paragraph in the third definition list item.

  Here's the third paragraph in the third definition list item.

ruby
: Here is some Ruby code.

  ```ruby
  puts "hello"
  ```

  Here is some more Ruby code.

  {format: ruby}
  ![Hello, World](hello.rb)

  That's as simple as it gets.

Here's a paragraph after the list.

Just as with list items, any leading whitespace after the line break is used to continue the definition list item, and is thus ignored.

With the rise of mobile and the narrower screen reading experience becoming the new default, definition lists may end up being more useful than tables in many Markua documents.

Finally, with definition lists, one thing you often want to do is link to a specific definition, not just to the list itself. This is useful to do, since in a document with many definitions, it’s helpful if the reader scrolls to the right spot or opens to the right page.

To do this, just define a span id on the element itself, and then link to it.

foo{#foo}
: This is foo.

bar{#bar}
: This is bar.

Note that if you define an id attribute above the first definition list item, what you are doing is defining an id on the entire definition list. As such, this does not work on any subsequent list item: in the following definition list, the {#definitions} is the id of the definition list. It is not the id of foo.

{#definitions}
foo{#foo}
: This is foo.

bar{#bar}
: This is bar.

To be clear, the following is not legal Markua:

This is not legal.

foo
: This is foo.

{#bar}
bar
: This is bar.

This is not legal.

If there was an id above foo, it would be legal, since it would be the id of the entire definition list. However, the id attribute above bar is not legal. Leanpub should ignore this id, and add an error to the list of errors.