Skip to content
Last updated

If and else tags

Products:RevelRevelReefReefRealmRealm
Plans:ProEnterpriseEnterprise+

The if and else tags let you conditionally render content in Markdoc. Use these tags with variables and functions to show the right content for the right user or context.

Syntax and usage

Use if when you want content to render only when a condition is true. Add else when you want fallback content when the if condition is not met.

Example syntax:

{% if equals($frontmatter.audience, "developer") %}
This guide shows advanced API setup steps.
{% else /%}
This guide shows a high-level overview.
{% /if %}

In Realm, you can chain multiple else branches with conditions. The final else /% branch acts as the default fallback.

{% if equals($userClaims.plan, "enterprise") %}
Access to enterprise-only docs.
{% else equals($userClaims.plan, "pro") /%}
Access to pro docs.
{% else /%}
Upgrade to unlock this section.
{% /if %}

Markdoc treats only undefined, null, and false as falsey. Values like 0, empty strings, and empty arrays are treated as truthy.

Conditional function reference

Use built-in functions to keep conditional expressions readable and composable.

FunctionReturnsDescription
equalsbooleanCompares values using strict equality. Useful for role, plan, or environment checks.
andbooleanReturns true when all parameters are truthy.
orbooleanReturns true when at least one parameter is truthy.
notbooleanNegates a boolean expression.
defaultmixedReturns a fallback value when the first parameter is undefined.
debugstringSerializes a value as JSON for debugging. Useful when testing variables in a condition.

Examples

The following examples show common conditional patterns for documentation.

Gate content using the front matter

Use front matter variables to switch content variants in one page.

---
releaseStage: beta
---

{% if equals($frontmatter.releaseStage, "beta") %}
{% admonition type="warning" %}
This feature is in beta and may change.
{% /admonition %}
{% else /%}
This feature is generally available.
{% /if %}

Combine built-in functions

Compose conditions for more specific rules.

{% if and(equals($userClaims.role, "customer"), not($userClaims.isExpired)) %}
Premium customer content.
{% else /%}
You need an active premium subscription.
{% /if %}

Use a custom function with if and else

Custom functions make repeated business logic reusable for authors.

Example function definition:

@theme/markdoc/schema.ts
export const functions = {
  isAfterDate: {
    transform(parameters) {
      const inputDateString = parameters[0];
      const inputDate = new Date(inputDateString);
      const currentDate = new Date();
      currentDate.setHours(0, 0, 0, 0);

      return inputDate < currentDate;
    }
  }
};

Example usage in content:

{% if and(isAfterDate("2026-06-01"), not(isAfterDate("2026-07-01"))) %}
{% admonition type="info" name="Sale" %}
Limited-time offer is active.
{% /admonition %}
{% else /%}
No active promotion.
{% /if %}

Best practices

Conditional tags are most useful when they improve relevance without making the document hard to maintain.

Keep conditions readable

Prefer simple expressions. Move repeated logic into custom functions.

Always include a fallback

Use a final else /% branch when content can be hidden for some users. Fallback text prevents empty sections.

Use stable variables

Base conditions on predictable values such as front matter, user claims, or environment flags. Avoid conditions that rely on inconsistent runtime data.

Test both paths

Preview pages with values that trigger both if and else branches. Confirm that hidden content does not leave confusing gaps.

Resources

Partial