In HTML, elements are rendered in either block mode or inline mode. The distinction is, on its face, quite simple:

• In block mode, elements are stacked vertically, with the bottom edge of one item up against the top edge of the next.
• In inline mode, elements are stacked horizontally, with the right edge of one item up against the left edge of the next (or vice versa if the page is in a language where text is written right-to-left). If there is not enough horizontal space to render all the consecutive inline-mode elements, the browser will insert a line break at an appropriate location, such as the end of an element or the end of a word within an element, and continue rendering on the next line.

Importantly, in inline mode, insertion of vertical space is not allowed (except by the automatic line-breaker, or by the <br> tag, which forces the line-breaker to break there). For instance, you cannot start a new paragraph in inline mode – instead, you have to leave inline mode, returning to block mode, and create a new block.

As an example, div elements are ordinarily rendered in block mode, while span elements are ordinarily rendered in inline mode. Here's how they look:

<div style="background-color: red;">Element 1</div>
<div style="background-color: yellow;">Element 2</div>

<hr>

<span style="background-color: red;">Element 1</span>
<span style="background-color: yellow;">Element 2</span>

It's possible to alter this behavior using CSS, but since our focus in this book is not HTML and CSS, we will leave it there. For more technical details on the HTML side of things, check out the Mozilla developer docs.

Block and inline mode in TiddlyWiki

Wikitext rendering in TiddlyWiki adds an additional layer of complexity. As TiddlyWiki reads wikitext, it is either reading in inline mode or block mode. In inline mode, it recognizes only the elements of wikitext that make sense in an inline context, such as links or bold formatting. In block mode, it recognizes elements that are blocks of their own, such as lists, blockquotes, or code snippets. Within block elements, TiddlyWiki enters inline mode; you re-enter block mode by leaving a blank line in your wikitext. (Note, however, that you cannot re-enter block mode with a blank line at all if you are inside certain elements that are inherently restricted to inline mode, like links or italic text – in this case you must close that element before adding a blank line.)

This is why you need a blank line on either side of, e.g., lists, for them to display correctly (see the following snippet for an example). If you don't put a blank line before the list, TiddlyWiki reads the first * as part of a paragraph – * is a perfectly valid character to have within a paragraph, after all – and the remainder of the list is read in inline mode, which usually won't look very good. Similarly, if you don't put a blank line after the list, TiddlyWiki stays in inline mode at the end of the final list item, and it will not start a new paragraph until it leaves inline mode.

A correct list:

* Item 1
* Item 2
* Item 3

Text after the correct list.

An incorrect list:
* Item 1
* Item 2
* Item 3
Text after the incorrect list.

Transclusion

Matters are complicated further by transclusion, which can make sense in either a block or an inline context, but usually not both at once. For instance, if you want to transclude a field that contains a phone number into the text of a paragraph, you probably want to do that in inline mode so you don't interrupt the paragraph and put the phone number on a separate line. On the other hand, if you transclude the text field of a long tiddler, you probably want to do that in block mode so all its paragraphs don't get squashed into one. (I'm discussing field transclusions here, but this generally applies to variable transclusions as well.)

In many cases, TiddlyWiki will do the right thing on its own: it chooses a mode based on whether you put blank lines around the reference or not. This can become unintuitive, however, when you transclude something within a widget. For instance, let's suppose we want to show the text of all meetings at which fudge was mentioned, with a horizontal line in between each:

<$list filter="[tag[Meeting]search[fudge]]">
  {{!!text}}

  ------
</$list>

This doesn't work right – can you spot the problem? There isn't a blank line before {{!!text}}, so the transclusion happens in inline mode! You can fix this either by putting a blank line just before {{!!text}}, or by forcing the transclusion to take place in block mode using the mode attribute of the $transclude widget:

<$list filter="[tag[Meeting]search[fudge]]">
  <$transclude $mode="block" $tiddler=<<currentTiddler>>/>

  ------
</$list>

You can read more about the $transclude widget and block/inline-mode transclusion in the TiddlyWiki documentation.

Inline-mode markup errors

A common cause of a tiddler displaying funny, which you're now prepared to understand and fix more easily, is an unclosed inline-mode element. For instance, suppose we have two paragraphs in a tiddler, and we open some italics and forget to close them in the first paragraph.

Here is my //first paragraph.

Here is my second paragraph.

You'll notice that the two paragraphs got smashed into a single paragraph – what's going on there?

If you inspect the content of the output tab in your browser's developer tools, as we learned how to do in When Things Go Wrong, you'll see this is the HTML TiddlyWiki generated for those paragraphs:

<div class="msbs-snippet">
Here is my <em>first paragraph.

Here is my second paragraph.</em>
</div>

The surrounding div is part of the snippet tooling used in this wiki, so you can focus in on its content, which is the result of rendering a complete tiddler (the snippet is stored in its own tiddler). The HTML equivalent to //// is an em element, short for emphasis.

Since we didn't ever close the italics, TiddlyWiki automatically inserted a matching closing tag at the end of the tiddler. Herein lies our problem: because em is an inline element, TiddlyWiki doesn't treat two consecutive newlines as a paragraph break within that element, so it doesn't generate a <p> tag and you don't get a new paragraph. An entire tiddler can get smashed together this way.

Takeaways