Lists

Creating lists in Homebrewery, using Markdown, is quite intuitive, and styling it isn’t half bad either. Homebrewery doesn’t add any special syntax for regular lists, but it does for definition lists (article to come soon).

Markup

Lists should contain content that is actually a list of related items, and there are basically two types of related content, ordered and unordered. An ordered list has items that come sequentially, like the cooking steps in a recipe. Markdown only accepts numeric lists (starting with 1. or 1) ), but they can be styled after-the-fact to use letters or roman numerals, etc. Ordered lists are rendered as <ol> HTML tags in the Preview pane. Unordered lists are made of items that are related, but don’t have any apparent order to them, like the ingredients list of a recipe. These are typically indicated with dashes, bullets, icons, etc. Unordered lists are output to the Preview pane as <ul> HTML tags. Regardless of the type of list, each item in the list is rendered between <li> tags within the greater list, and each item is preceded by a list marker (either a type of bullet point or a number/letter/roman numeral).

Using Markdown, you can write a list by simply using the appropriate list marker followed by a space:

An unordered list
- Pepperoni
- Cheese
- Dough
- Red sauce

An ordered list
1. Roll out dough
2. Spread sauce
3. Add toppings
4. Bake

Note, with ordered lists, you don’t actually need to increment your list marker– if every item is part of the same underlying list, it will automatically increment for you. The below will render the same as the ordered list above:

An ordered list
1. Roll out dough
1. Spread sauce
1. Add toppings
1. Bake

Nesting is done with indentations for each level of nesting you want.

The amount of spaces before your item is equal to the number of characters used in the list marker of the previous item. For the next level of list, the marker should line up with the content of the parent item. This is different from the rules for indentation in the Legacy renderer, which simply uses 2 spaces for each level.

My nested *unordered* list (2 spaces aligns the marker with the parent list)
- Pepperoni
  - the cheap stuff
- Cheese
  - mozzarella
  - parmesan
- Dough
- Red sauce

My nested *ordered* list (3 spaces aligns the marker with the parent list)
1. Roll out dough
   1. lay dough on clean counter
   2. use rolling pin to press dough
   3. roll from center to the outer edge
2. Spread sauce
3. Add toppings
   1. cheese first
   2. pepperoni second
4. Bake
1000. A big number for the marker requires...
      1. ....more space to align the marker with the previous item's content.

Taking just the first list, the output is rendered to HTML as a <ul> element with four <li> child elements. And, within two of those child elements, each has another <ul> element inside with more items inside them. Here is the output then for the second, ordered, list:

<ol>
  <li>Roll out dough
    <ol>
      <li>lay dough on clean counter</li>
      <li>use rolling pin to press dough</li>
      <li>roll from center to the outer edge</li>
    </ol>
  </li>
  <li>Spread sauce</li>
  <li>Add toppings
    <ol>
      <li>cheese first</li>
      <li>pepperoni second</li>
    </ol>
  </li>
  <li>Bake</li>
  <li>A big number for the marker requires…
    <ol>
      <li>….more space to align the marker with the previous item’s content.</li>
    </ol>
  </li>
</ol>

Styling

Like everything else written in Markdown, there isn’t a huge variety of styling changes you can make unless you start applying CSS. For lists, a common goal is to change the type of list– for instance, making the list markers into alphabetical letters, or empty circles, or specific little icons or images.

To start, you’ll have to target your list with a CSS selector. You might think to use the Homebrewery injector syntax to apply styles directly, or to inject a class name into the list, like this:

- Pepperoni
  - the cheap stuff
- Cheese
  - mozzarella
  - parmesan
- Dough
- Red sauce
{color:red,red-list}

Unfortunately, you will find that this colors red and applies the .red-list class name to only the last item on the list, rather than the whole list. Dropping the color:red bit, you could still work with the class name in your Style Editor, with the relatively new :has() selector, like this:

.page ul:has(.red-list) {
  color: red;
}

Alternatively, you could wrap your list in a named div, and then target either the div directly or any lists inside of it for the same result:

{{red-list
- Pepperoni
  - the cheap stuff
- Cheese
  - mozzarella
  - parmesan
- Dough
- Red sauce
}}

.page .red-list ul {
  color: red;
}

Now that you know how to target the entire <ul> or <ol> element, rather than the last <li> element, you can apply list-level CSS properties, like list-style-type:

.page .red-list ul {
  color: red;
  list-style-type: lower-roman;
}

Styling Nested Levels

If you are styling lists with multiple levels, and wanting each level to have a slightly different look, you’ll need to think about the selectors you use in your CSS. Continuing with the above example of the last ingredient list, here is how I would approach styling it:

.page .red-list > ul {
  color: red;
  list-style-type: disc;
  & li > ul {
    color: orange;
    list-style-type: circle;
  }
}

Note, the above CSS is using a newer CSS feature called CSS Nesting— not to be confused with our own nesting lists– which allows us to nest selectors to make CSS easier to read and write.

Styling the List Items

Up to now the focus was on styling the entire lists (or lists within lists). You can also style the list item (<li>) elements. Either you want to style each item separately or, more likely, you want to style some things about list items that can only be done on that element. Chiefly, the space between the list marker and the beginning of the text.

To increase the space between the list marker and the following text, target the list item and add some padding to the left:

.page .red-list > ul li {
  padding-left: 15px;
}

Close

There is a lot more to say about lists than is covered here. Surprisingly more (at least, I was caught off guard a bit when doing a little research for this post). I hope to come back to cover some of the additional aspects of lists in Markdown, but likely those discussions will happen as tangents while covering some other things. In the meantime, I suggest taking a look at the Commonmark specs for lists— Commonmark being the specific flavor of Markdown that the Homebrewery uses as its basis.

Hopefully this is enough to get most people started with lists. If there are additional details that you think should be added, please find me on Discord or Reddit.