Markdoc components

Markdoc components are tags you write in API Portal page content to render layout blocks and live data from your portal, such as product cards, article lists, buttons and a contact form. You write them in the page editor under Portal, Pages. This page lists each tag with the attributes it actually reads.

How do you write a component tag?

A tag opens with a name and attributes in curly braces and percent signs. Tags that wrap content have a closing tag. Tags that stand alone close themselves with a slash.

{% productCard slug="weather-api" /%}

{% callout title="Rate limits" %}
Each plan sets its own limits.
{% /callout %}

Attribute values in quotes are text. Numbers and true or false go without quotes, for example numberOfProducts=3.

Where can you use each component?

The same layout components work in every portal page. Product tags and variables depend on which page you are editing.

A product's Product Overview, which you edit on the product, supports the layout components and the product and article cards.

How do you discover every component on your portal?

Open /kitchen_sink on your own portal, for example https://your-portal-domain/kitchen_sink. It renders each layout component with its source, lists the portal's colour variables, and ends with a sandbox where you can try tags.

The gallery focuses on layout components. The product, article and contact form tags are covered on this page.

Which components does the page editor insert?

The editor's Insert toolbar has three groups. Media holds Image and Video, Content holds Callout and Linkwrap, and Layout holds Section and Grid. Each opens a short dialog, then writes the tag at your cursor.

columns and rows take a CSS grid template, for example columns="repeat(3, 1fr)" for three equal columns. Set columnGap and rowGap, for example columnGap="1.5rem", to space the items, because both default to zero.

Which other layout components can you use?

The rest of the layout set has no toolbar button, so you type the tag. /kitchen_sink shows most of them with working source you can copy.

Which product and article components can you use?

These tags pull live data from your portal. Product and article cards work on any portal page. The three product detail tags work only in the Product Page.

{% productCards numberOfProducts=3 /%}

{% articleCard id="getting-started" /%}

{% articlesCollection collection="guides" view="card" /%}

{% roundedButton target="/products" variant="primary" %}
Browse APIs
{% /roundedButton %}

{% contactForm mode="inline" /%}

What variables can you use in a page?

Variables start with a dollar sign and are filled in by the portal. Which ones exist depends on the page you are editing.

Use $isAuthenticated with Markdoc's if tag to show a different block to signed-in developers, for example a link to their subscriptions in place of a sign-up button. This changes what each visitor sees. It does not keep content private, so do not put anything confidential inside it.

{% if $isAuthenticated %}
[Go to your subscriptions](/subscriptions)
{% else /%}
[Create an account](/signup)
{% /if %}

Troubleshooting

Where to next