Expressing conditions

Bbmd makes it much easier to express conditions in your Markdown documents by allowing blocks to chain simple methods like .if(), .default(), and .change(). This keeps your document factories clean and easy to read, even when handling complex conditional logic.

if

Keep content only when the condition is truthy. Clears the block when falsy.

const isAdmin = true
b.p`Welcome, admin.`.if(isAdmin)

Welcome, admin.

When the condition is falsy, the block becomes empty and renders as null:

const isAdmin = false
b.p`Welcome, admin.`.if(isAdmin)

emptyIf

The inverse of .if() — clears content when the condition is truthy, keeps it when falsy.

const isUnstable = true
b.p`This API is stable.`.emptyIf(isUnstable)

const isUnstable = false
b.p`This API is stable.`.emptyIf(isUnstable)

This API is stable.

defaultIfEmpty

Provide fallback content for empty blocks (an empty block is one that has been cleared by .if() or .emptyIf(), or was given content that coerces to false). This is useful for handling optional data without needing to write explicit conditions.

const userName = "" // 👈 could also be null, undefined, or any other falsy value
b.p(userName).default("Anonymous")

Anonymous

Can be combined with .if() to provide fallbacks for conditionally hidden content

const user: User | null = null;
b.p`Premium content.`.if(user).default("Please log in.")

Please log in.

change

Pass the block to a transform function and return the result. Useful for conditional wrapping or modification without breaking a chain and also allows for extremely declarative conditions.

const isUrgent = true

b.p`Fix this bug.`.change((block) => {
  if (isUrgent) return block.bq().alert("warning")
  return  block
})

> [!WARNING]
> Fix this bug.

_MarkdownBlockquoteBlock [alert=warning]
└── MarkdownParagraphBlock
    └── "Fix this bug."

Note that .change() is just syntax sugar for grabbing the current block, modifying it, and returning it. You can achieve the same effect by breaking the chain and reusing the block variable:

const isUrgent = true
let block = b.p`Fix this bug.`
if (isUrgent) block = block.bq().alert("warning")
block

> [!WARNING]
> Fix this bug.

_MarkdownBlockquoteBlock [alert=warning]
└── MarkdownParagraphBlock
    └── "Fix this bug."