Temporal Documentation Site Components

This document provides detailed information about the components used across the Temporal documentation site.

The site is built with Docusaurus, a static site generator. Static site generation offers fast load times by pre-building content and serving it as static files. This reduces server load and increases security by eliminating dynamic server-side processes or databases.

Our components are reusable building blocks, typically created with React. They enhance our content with elements that can be used across multiple pages. These components are flexible and configurable at the point of use. By simplifying complex customizations into easy-to-use components, we make our documentation easier to read, maintain, and update.

Our components handle tasks like displaying content, managing layouts, and handling images. This guide shows you how to import, use, and customize these components in your work. Whether you’re using core components or experimenting with new ones, this guide helps you make the most of them.

Finding Components
Adding Components to This Repository
Using Components in MDX Source Files
Using IntegrationsGrid
Using CaptionedImage
Using Video
Using DocsTable
Using RelatedRead
Using ToolTipTerm
Using SdkGuideLinks
Using AnnotatedCode
Using ReleaseNoteHeader

Finding Components

Our components are located in the src/components folder at the root of this repository.

index.js: Provides a single entry point for importing all components into your documentation files.
elements: These are pre-built on-screen elements, usually used in a single place or sometimes not at all. They were carried over from earlier versions of the site.
formatting: These components are used for text layout, often within tables. They help with formatting the content for better readability.
images: Contains components for presenting images on-screen, helping to manage how images are displayed across the site.
info: This folder includes components for presenting additional content, often used to enhance the user experience with supplementary information.
experimental: This folder contains components that are not currently used on the site. These are either for testing or were previously part of ongoing development.

Components are reusable, self-contained units of code used for our Documentation site. As shown in this file tree, our components are built using JavaScript and React. Components often have associated CSS files to manage styling, although this is optional. While some components include custom styling for layout or presentation, others rely on external styles or omit styling altogether.

Adding Components to This Repository

When adding a patch with new components, please follow these directions:

Test your component across multiple platforms including mobile, desktop, and a variety of browsers, as well as both light mode and dark mode.
Use ARIA attributes to support accessibility, ensuring the component is usable by all.
Register your component in the index.js file, making it available for global import.
Ensure your component follows our naming conventions (for example, PascalCase for React components) and the structure used in this repository.
Use appropriate 'src/components' folder hierarchies and document hierarchy changes in this document.
Update this documentation file with your component’s details, including usage examples and any configuration options. Follow the existing format and style for consistency.
Include clear and concise usage examples, and note any potential edge cases or known issues, as well as future development directions.

Testing your Component

Light and Dark Mode: Make sure all elements of your components works properly in both light and dark modes.
Browser Geometries and Edge Cases: Make sure your components resize appropriately with Web browsers, and render correctly on mobile (both phone and tablet). Provide alternate presentations if needed for smaller real estate. On Desktop, make your browser window both tall and short, wide and narrow.
Cross-browser support: Test on Chrome and Safari as a minimum. "React aims for cross-browser compatibility, but subtle differences can arise due to how browsers implement web standards or handle specific features. While React itself abstracts away many of these inconsistencies, some areas may require attention."
Accessibility checks: Test accessibility using a screen reader.
Crowdsource: Use Vercel deployments to bug-bash your component.

Reach out for help if issues arise that compromise component functionality. We may be able to help you work out a solution.

Using Components in MDX Source Files

Importing components

You must import components before use. For example:

import { CaptionedImage } from '@site/src/components';

import { RelatedReadContainer, RelatedReadItem } from '@site/src/components';

As a rule, place your import statement at the top of your MDX file below the front matter. Not all MDX files in this repository follow this rule, especially older documents.

Note: All sanctioned components are enumerated in 'src/components/index.js'. You shouldn't use any other import paths for Temporal components.

Adding components to MDX files

Once imported, you can use components in angle brackets, making sure to set any properties ("props") in their use. For example:

<RelatedReadItem
    path="/cloud/metrics/prometheus-grafana"
    text="How to set up Grafana with Temporal Cloud observability"
    archetype="feature-guide"
/>

Global Imports

Because this repository uses index.js to vend its components, you can import all components as once:

import * as Components from '@site/src/components';

Components imported this way use the "Components." prefix before their name:

<Components.RelatedRead>
...Content that is folded away...
</Components.RelatedRead>

Using IntegrationsGrid

Role: Display a searchable, filterable grid of Temporal integrations with partner tools and services.

The component renders a search bar, two rows of filter pills (SDK and Tag), and a card grid. Each card shows the integration name, a short description, tag badges, and an SDK icon when applicable. Cards that link to external sites display an external link indicator and open in a new tab.

How to import:

import IntegrationsGrid from '@site/src/components/IntegrationsGrid';

Usage:

<IntegrationsGrid />

Props

Prop	Type	Default	Description
`defaultSdks`	`SDK[]`	`[]`	Pre-selects SDK filters on load. Used on per-SDK integrations pages.

For example, the Python SDK integrations page pre-filters to Python:

<IntegrationsGrid defaultSdks={["Python"]} />

Valid SDK values are "Go", "Java", "Python", "TypeScript", and "Ruby".

Filter behavior

The component has three filter dimensions that work together:

Search: Free-text search across integration names, descriptions, and tags.
SDK pills: Filter by language SDK. Selecting "Language-agnostic" shows integrations that have no SDK (such as Temporal Cloud metrics integrations). Multiple SDK pills can be active at once (OR logic).
Tag pills: Filter by category tag. Multiple tag pills can be active at once (OR logic).

When filters from different dimensions are active, they combine with AND logic. For example, selecting the "Python" SDK pill and the "Observability" tag pill shows only Python observability integrations.

Where the component is used

/integrations (top-level page, no default filters)
/develop/java/integrations (pre-filtered to Java)
/develop/python/integrations (pre-filtered to Python)
/develop/ruby/integrations (pre-filtered to Ruby)
/develop/typescript/integrations (pre-filtered to TypeScript)

Adding a new integration

Integration data lives in src/components/IntegrationsGrid/integrations-data.ts. Add a new entry to the integrations array with the following shape:

{
  name: "Partner Name",
  description: "One sentence describing what this integration does with Temporal.",
  tags: ["Agent framework"],
  sdk: "Python",
  href: "/develop/python/integrations/partner-name",
}

Fields:

Field	Type	Required	Description
`name`	`string`	Yes	Display name of the integration.
`description`	`string`	Yes	One-sentence summary shown on the card.
`tags`	`string[]`	Yes	One or more category tags. Existing tags: `Agent framework`, `Agent observability`, `Framework`, `Governance`, `Observability`, `Temporal Cloud`. New tags appear in the filter row automatically.
`sdk`	`SDK`	No	The language SDK this integration targets. Omit for language-agnostic integrations (such as Temporal Cloud metrics exporters).
`href`	`string`	Yes	Link target. Use a relative path for internal docs (e.g. `/develop/python/integrations/langsmith`). Use a full URL for external partner docs (e.g. `https://docs.partner.com/temporal`). External links automatically get an external icon and open in a new tab.

Multi-SDK integrations: If an integration supports multiple SDKs with different guide pages, add a separate entry for each SDK. Both entries can share the same name. For example, LangSmith has one entry for Python and one for TypeScript, each with a different href.

Language-agnostic integrations: Omit the sdk field. These integrations appear when the "Language-agnostic" SDK filter is selected and do not display a language icon on the card.

Using CaptionedImage

CaptionedImage replaces older image inserts methods, and complies with light and dark mode and accessibility. It is meant for images that use captions. You can still use standard image inserts (![AX text](/path/to/image)) as needed.

Usage:

<CaptionedImage
    src="/path/to/your/image"
    title="your caption"
/>

Images are normally stored in the '/static' folder in img or diagrams.

Dark mode images

To provide a separate image for dark mode, use the srcDark prop:

<CaptionedImage
    src="/diagrams/my-diagram.svg"
    srcDark="/diagrams/my-diagram-dark.svg"
    title="My diagram"
    alt="Description of the diagram"
/>

When srcDark is provided, both images are rendered in the DOM and the browser loads both upfront. CSS toggles visibility based on the active theme, so switching between light and dark mode is instant with no loading delay. When srcDark is omitted, the component renders a single image as usual.

Zooming images

When images are complex and may not render in a readable fashion on normal monitors, you can enable a minimal form of zooming by setting the zoom prop to true:

<CaptionedImage
    src="/path/to/your/image"
    title="your caption"
    zoom="true"
/>

One click will zoom out, another will zoom back. Most rendering will allow readers to pull the image around to view all parts of the image. On non-mobile systems, cursors will change to interactive elements when hovered above zoomable items to indicate interaction.

Using Video

Video embeds a YouTube video behind a click-to-play facade. It enforces a consistent, centered, width-constrained appearance across the site, always points at the youtube-nocookie.com embed domain, and defers loading the real iframe (and YouTube's tracking scripts) until the reader clicks the thumbnail.

Usage:

<Video videoId="EwweiH2rd7M" title="What is the Temporal Platform?" />

Prop	Type	Required	Description
`videoId`	`string`	Yes	The YouTube video ID (the `v=` value from a `youtube.com/watch` URL).
`title`	`string`	Yes	A descriptive title. Used as the iframe's accessible title, the play button's `aria-label`, and the "Watch" link generated for the LLM Markdown pipeline (see MARKDOWN_PIPELINE.md).
`maxWidth`	`string`	No	Escape hatch to override the default width for a documented one-off exception. Most pages should omit this and use the standard width.

Because Video generates the "Watch: {title}" link for the LLM Markdown feed automatically, you no longer need to hand-write a separate Watch [Title](url) sentence purely for that purpose. You can still add a short lead-in sentence for human readers (for example, "Watch a short overview:") above the component.

Not yet supported: embedding a YouTube playlist (videoseries?list=...). The two pages that still embed a playlist (docs/develop/python/workflows/versioning.mdx and docs/develop/dotnet/workflows/versioning.mdx) continue to use a raw <iframe> until playlist support is added.

Using DocsTable

In certain rare instances, standard Markdown tables won't work for our needs. They may contain information that is complex enough that in-line table format becomes unmaintainable and cumbersome. DocsTable addresses this, breaking the material down into individual cells that use standard Markdown formatting that is not supported in Markdown tables. For example, you can use bullet points instead of HTML lists, and code fencing instead of <tt> tagging.

Usage:

<DocsTable Columns = {["", "Column 1", "Column 2"]} >

Row Title

<NewDocsCell />

Column 1 Markdown content

<NewDocsCell />

Column 2 Markdown content

</DocsTable>

Some notes:

<NewDocsCell /> separates cell content. It only appears between cells. You do not need it at the start or end of your cell contents.
For empty cells, add a blank line and a <NewDocsCell />.
At this time, keep <NewDocsCell /> on its own line with space above and below it. yarn format will mess up your tables otherwise. This requirement may be addressed in a future update.

Using RelatedRead

Role: Create a list of related items, with summaries and archetypes

Usage:

<RelatedReadContainer>
  <RelatedReadItem path="/cloud/metrics/prometheus-grafana"
    text="How to set up Grafana with Temporal Cloud observability"
    archetype="feature-guide" />
  <RelatedReadItem path="/cloud/worker-health"
    text="How to monitor Worker Health with Temporal Cloud Metrics"
    archetype="feature-guide" />
  <RelatedReadItem path="/cloud/service-health"
    text="How to monitor Service Health with Temporal Cloud Metrics"
    archetype="feature-guide" />
</RelatedReadContainer>

Archetypes:

encyclopedia
feature-guide
feature-summary

Using ToolTipTerm

Role: Provide definitions or background information at the point of use.

Usage:

<ToolTipTerm term="your_term_name" />

For example:

Temporal Cloud strives to maintain a <Components.ToolTipTerm term="P95" /> replication delay of less than 1 minute.

Defining terms

Terms are stored in static/term. Use standard Markdown, with files named with '.md'. You may use links, images, and other standard elements in the definition. This helps when you want to define a term and provide a link to further coverage.

For example:

docs% ls static/terms/P95*
static/terms/P95.md
docs% cat static/terms/P95.md 
P95 refers to the 95th percentile of a data set.
It identifies values that are greater than or equal to 95% of that set.
docs%

Specifying content with a path

For reasons of capitalization, spelling, or multiple reader sets (experts vs beginners, for example), you may want to vary the content of the tooltip. Use the src prop to select a different md file. For example:

<Components.ToolTipTerm term="fail over" src="failover" />

Manually Overriding Content

Use the tooltip prop to add non-reusable content specific to one tooltip term.

<Components.ToolTipTerm term="your term" tooltip="any custom content you want to add" />

Using SdkGuideLinks

Role: Render a vertical list of SDK guide links, each with a colored block icon and label, linking readers to the relevant SDK-specific page.

How to import:

import { SdkGuideLinks } from '@site/src/components';

Standard usage

Pass a path prop and the component generates links for all eight SDKs automatically. The path is appended to /develop/<sdk>/, so you only need the portion after the SDK segment.

<SdkGuideLinks path="client/temporal-client" />

This produces links to /develop/go/client/temporal-client, /develop/java/client/temporal-client, and so on for all supported SDKs.

Filtering to specific SDKs

Use the filter prop to show only a subset of SDKs. Pass an array of SDK identifiers.

<SdkGuideLinks path="client/temporal-client" filter={['go', 'java', 'python']} />

Valid SDK identifiers: go, java, dotnet, php, python, ruby, rust, typescript.

Custom links

When SDK guide pages do not follow the standard /develop/<sdk>/<path> pattern, pass explicit links with the links prop. The path and filter props are ignored when links is provided.

<SdkGuideLinks links={[
  { name: 'goLangBlock',     href: '/develop/go/custom/path',         label: 'Go' },
  { name: 'pythonBlock',     href: '/develop/python/custom/path',     label: 'Python' },
  { name: 'typeScriptBlock', href: '/develop/typescript/custom/path', label: 'TypeScript' },
]} />

Valid name values for the block icons: goLangBlock, javaBlock, dotnetBlock, phpBlock, pythonBlock, rubyBlock, rustBlock, typeScriptBlock.

Props

Prop	Type	Required	Description
`path`	`string`	Yes, unless `links` is provided	Path segment appended to `/develop/<sdk>/` for each SDK link.
`filter`	`string[]`	No	Limits generated links to the specified SDK identifiers. Only applies when using `path`.
`links`	`object[]`	Yes, unless `path` is provided	Explicit list of links. Each item requires `name`, `href`, and `label`. Overrides `path` and `filter`.

Where the component is used

/temporal-client — links to the Temporal Client feature guide for each SDK

Using AnnotatedCode

Role: Let readers click concept pills to highlight matching lines in a code sample and show a short description.

Put a normal Markdown fence as children so the sample stays in the MDX. Put annotations inline on the page next to that fence.

How to import:

import { AnnotatedCode } from '@site/src/components';

Usage

Example from the Worker performance page (poller autoscaling):

<AnnotatedCode
  annotations={[
    {
      label: 'Workflow Task poller',
      description: 'Autoscales the number of pollers for Workflow Tasks based on load.',
      lines: [2],
    },
    {
      label: 'Activity Task poller',
      description: 'Autoscales the number of pollers for Activity Tasks based on load.',
      lines: [3],
    },
    {
      label: 'Nexus Task poller',
      description: 'Autoscales the number of pollers for Nexus Tasks based on load.',
      lines: [4],
    },
  ]}
>
```go
w := worker.New(c, "my-task-queue", worker.Options{
  WorkflowTaskPollerBehavior: worker.NewPollerBehaviorAutoscaling(worker.PollerBehaviorAutoscalingOptions{}),
  ActivityTaskPollerBehavior: worker.NewPollerBehaviorAutoscaling(worker.PollerBehaviorAutoscalingOptions{}),
  NexusTaskPollerBehavior: worker.NewPollerBehaviorAutoscaling(worker.PollerBehaviorAutoscalingOptions{}),
})

```

lines are 1-based line numbers within the fence. Use an empty array when a concept has no lines to highlight in that sample.

Optional color on an annotation: indigo, magenta, blue, or amber. If omitted, tones rotate in that order.

Optional hint prop overrides the default “Highlight a concept” text above the pills.

Props

Prop	Type	Required	Description
`annotations`	`object[]`	No	Each item needs `label`, `description`, and `lines`. Optional `color`.
`hint`	`string`	No	Text above the pills. Defaults to `Highlight a concept`.
`children`	Markdown fence	Yes	The code sample to display and highlight.

LLM markdown

Registered as strip-tag in the MDX → Markdown pipeline: wrapper tags are removed and the fence content is kept. Keep annotation copy in the MDX annotations prop so authors edit it on the page.

Where the component is used

Worker Versioning — Worker options concepts
Worker performance — poller autoscaling options
Environment configuration — TOML Cloud profile fields
Task Queue Priority and Fairness — priority / fairness options
Child Workflows design pattern — async start concepts

Using EventHistoryWalkthrough

Role: Step-by-step interactive walkthrough of a Workflow Definition, showing which statements the Worker handles internally and which send a Command to the Temporal Service (and, for demos with an Events column, the Events those Commands produce). Used on the docs/encyclopedia/event-history/*.mdx pages — four walkthroughs per page (how code maps to Commands, how Commands map to Events, how History Replay works, and a non-determinism example), all built from the single WalkthroughDemo component parameterized by props.

Content is authored directly in the MDX page, not in a data file: a Markdown code fence, followed by one <WalkthroughStep> per step. This keeps the code sample and the steps describing it in the same file, and lets the LLM markdown pipeline render real content instead of an opaque placeholder.

How to import:

import { WalkthroughDemo, WalkthroughStep, WalkthroughCommand, WalkthroughEvent } from '@site/src/components';

WalkthroughStep/WalkthroughCommand/WalkthroughEvent never render anything themselves — they're read for their props/children by the parent WalkthroughDemo.

Usage

<WalkthroughDemo ariaLabel="How Workflow code maps to Commands" commandsLabel="Commands issued">

```csharp
[Workflow]
public class PizzaWorkflow
{
    // ...
}

Prose describing this step. Plain Markdown — paragraphs, lists, links, and inline code all work.

A bullet
Another bullet

The Worker issues a Command here.

```

A demo with an Events column also passes eventsLabel, e.g. <WalkthroughDemo ariaLabel="..." commandsLabel="Commands" eventsLabel="Event History"> — omit eventsLabel for a Commands-only demo (no Events column renders). commandsLabel/eventsLabel are exactly the ledger column headers shown in the UI, so they're what differentiate one walkthrough from another; the four pages' walkthroughs use:

Walkthrough	`ariaLabel`	`commandsLabel`	`eventsLabel`
Code maps to Commands	How Workflow code maps to Commands	Commands issued	(omitted)
Commands map to Events	How Workflow Commands map to Events	Commands	Events
History Replay	How History Replay provides Durable Execution	Commands	Event History
Non-determinism example	Example of a non-deterministic Workflow	Commands created	Relevant History Events

lines is a comma-separated list of 1-based line numbers/ranges into the fence ("7-8,14-17,21-25"), highlighted while that step is active. Omit it for a step that highlights nothing.

kind (optional) is one of internal, command, service, crash, replay — drives the step's badge.

phase (optional, used by the History Replay and non-determinism walkthroughs) groups consecutive steps under a shared label, e.g. phase="History Replay".

A <WalkthroughCommand>/<WalkthroughEvent> value containing a " should use single quotes for the JSX attribute (details='...'), matching the example above — the transformer's prop parser tracks the specific quote character used, so a double quote inside a single-quoted value (or vice versa) is safe.

Props

`WalkthroughDemo` prop	Type	Required	Description
`ariaLabel`	`string`	Yes	Accessible label for the demo region.
`commandsLabel`	`string`	No	Commands column header. Defaults to `Commands`.
`eventsLabel`	`string`	No	Events column header. Omit for a Commands-only demo.
`children`	Markdown + JSX	Yes	A code fence followed by `<WalkthroughStep>` elements.

`WalkthroughStep` prop	Type	Required	Description
`title`	`string`	Yes	Step heading.
`kind`	`string`	No	`internal` \| `command` \| `service` \| `crash` \| `replay`.
`phase`	`string`	No	Groups this step under a shared phase label.
`lines`	`string`	No	Line numbers/ranges to highlight, e.g. `"7-8,14-17"`.
`children`	Markdown	Yes	The step's prose body, plus any `WalkthroughCommand`/`WalkthroughEvent` entries.

`WalkthroughCommand`/`WalkthroughEvent` prop	Type	Required	Description
`label`	`string`	Yes*	The Command/Event name.
`details`	`string`	No	Extra detail shown after the label.
`tone`	`string`	No	Visual tone (`command`, `direct`, `indirect`, `plain`).
`status`	`string`	No	`matched` or `mismatch` (History Replay/non-determinism ledger).
`expected`	`string`	No	What was expected instead, shown alongside a `mismatch` status.
`divider`	`string`	No*	Renders a labeled divider instead of an entry (*`label` not required when set).

LLM markdown

Registered as event-history-demo/walkthrough-step/walkthrough-entry in the MDX → Markdown pipeline (scripts/component-handlers/event-history-walkthrough.mjs): the fence passes through verbatim, and each step renders as a #### Step N: Title heading with its kind, prose, and any Command/Event entries, using the enclosing tag's commandsLabel/eventsLabel as the ledger group headers.

Where the component is used

Event History walkthroughs (docs/encyclopedia/event-history/{go,java,python,typescript,dotnet}.mdx) — all four walkthroughs on all five pages.

Using ReleaseNoteHeader

Role: To provide a consistent component for adding, updating, and removing release stages on different features.

Usage:

In /src/constants, update the featureReleaseTypes.js file to include the release stage for the feature you want.

Example: serverlessWorkers: "prerelease"

Then on the pages you want it to show, add this to the top of the content, right below the frontmatter. The featureName prop is how you share the release stages you add to featureReleaseTypes.js across pages.

import { ReleaseNoteHeader } from '@site/src/components';

<ReleaseNoteHeader
  featureName="nexus"
/>

Or you can choose one of these variations.

Use the type prop to set a specific type if the release stage is only for one page.

<ReleaseNoteHeader
  type="publicPreview"
/>

Add children for more detailed messaging.

<ReleaseNoteHeader featureName="serverlessWorkers">
  To request access during Pre-release, create a [support ticket](/cloud/support#support-ticket) or contact your account team.
  APIs are experimental and may be subject to backwards-incompatible changes.
  [Sign up for updates](https://temporal.io/pages/serverless-workers-updates) to be notified when Serverless Workers reach Public Preview.
</ReleaseNoteHeader>

Show the supported languages by using the languages prop.

<ReleaseNoteHeader
  type="prerelease"
  languages={["Go", "TypeScript", "Java", ".NET", "Python"]}
/>

Use the href prop to make the children content a link.

<ReleaseNoteHeader
  featureName="serverlessWorkers"
  href="https://temporal.io/pages/serverless-workers-updates"
>
  Sign up for updates to be notified when Serverless Workers reach Public Preview.
</ReleaseNoteHeader>

Uh oh!

FilesExpand file tree

COMPONENTS.md

Latest commit

History

COMPONENTS.md

File metadata and controls

Temporal Documentation Site Components

Finding Components

Adding Components to This Repository

Testing your Component

Using Components in MDX Source Files

Importing components

Adding components to MDX files

Global Imports

Using IntegrationsGrid

Props

Filter behavior

Where the component is used

Adding a new integration

Using CaptionedImage

Dark mode images

Zooming images

Using Video

Using DocsTable

Using RelatedRead

Using ToolTipTerm

Defining terms

Specifying content with a path

Manually Overriding Content

Using SdkGuideLinks

Standard usage

Filtering to specific SDKs

Custom links

Props

Where the component is used

Using AnnotatedCode

Usage

Props

LLM markdown

Where the component is used

Using EventHistoryWalkthrough

Usage

Props

LLM markdown

Where the component is used

Using ReleaseNoteHeader