annotated code component (#4953)

* annotated code

* refactor annotatedcode to keep in mdx and update colors

* add it on more pages

* build-it-component

* add to components.md

Author: jsundai

COMPONENTS.md

@@ -25,6 +25,7 @@ Whether you’re using core components or experimenting with new ones, this guid
 - [Using RelatedRead](#using-relatedread)
 - [Using ToolTipTerm](#using-tooltipterm)
 - [Using SdkGuideLinks](#using-sdkguidelinks)
+- [Using AnnotatedCode](#using-annotatedcode)
 - [Using ReleaseNoteHeader](#using-release-note-header)
 
 ## Finding Components
@@ -482,6 +483,78 @@ Valid `name` values for the block icons: `goLangBlock`, `javaBlock`, `dotnetBloc
 
 - `/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{}),
+})
+```
+</AnnotatedCode>
+```
+
+`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 ReleaseNoteHeader
 
 Role: To provide a consistent component for adding, updating, and removing release stages on different features.

MARKDOWN_PIPELINE.md

@@ -124,7 +124,7 @@ Each component maps to a strategy in `COMPONENT_REGISTRY` (in `scripts/mdx-to-md
 | `QuickstartCards`, `PatternCards` | `cards` | Markdown link list parsed from the inline `items={[{href,title,description}]}` prop |
 | `ZoomPanPinch` | `transparent` | Wrapper stripped; inner content passed through |
 | `DocCardList`, `CardList`, `LandingCard`, `ThemedImage`, `SdkSvg`, `CloudRegionCount`, `RetrySimulator`, `ServerlessWorkerDemo`, `OperationsTable`, `InvitationContent` | `strip-block` | Removed entirely (visual/dynamic, no extractable text) |
-| `DL`, `DT`, `DD`, `DefinitionList` | `strip-tag` | Tags stripped, text content kept |
+| `DL`, `DT`, `DD`, `DefinitionList`, `AnnotatedCode` | `strip-tag` | Tags stripped, text content kept |
 | `details` / `summary` | `details` / `summary` | `<summary>` becomes a heading; body expanded inline |
 
 **Transclusion.** Components imported from a Markdown file

docs/design-patterns/child-workflows.mdx

@@ -7,6 +7,7 @@ description: "Decomposes complex Workflows into smaller, reusable units. Each ch
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import { AnnotatedCode } from '@site/src/components';
 
 ## Overview
 
@@ -167,13 +168,33 @@ In Go, `workflow.ExecuteChildWorkflow()` returns a `ChildWorkflowFuture`, and ca
 ### Asynchronous Child Workflow
 
 The following example starts a Child Workflow asynchronously with an ABANDON policy.
-The parent receives the child's execution info without waiting for completion:
+The parent receives the child's execution info without waiting for completion. Select a concept to highlight the matching lines:
 
 <Tabs groupId="language" queryString>
 <TabItem value="python" label="Python">
-
+<AnnotatedCode
+  annotations={[
+    {
+      label: 'Parent Close Policy',
+      description:
+        'Controls what happens to the Child Workflow when the parent closes. ABANDON lets the child keep running after the parent completes.',
+      lines: [14],
+    },
+    {
+      label: 'Workflow Id',
+      description:
+        'Gives the Child Workflow a stable identity for tracking, querying, and deduplication in the UI.',
+      lines: [13],
+    },
+    {
+      label: 'Async start',
+      description:
+        'Starts the Child Workflow without waiting for it to finish. The parent continues after the child has started.',
+      lines: [10, 11, 12, 13, 14, 15],
+    },
+  ]}
+>
 ```python
-# workflows.py
 from temporalio import workflow
 from temporalio.workflow import ParentClosePolicy
 
@@ -183,28 +204,41 @@ from child_workflows import ChildWorkflow
 class ParentWorkflow:
     @workflow.run
     async def run(self, input: str) -> str:
-        # Async call - returns handle once child starts
         handle = await workflow.start_child_workflow(
             ChildWorkflow.run,
             input,
             id=f"child-{workflow.uuid4()}",
             parent_close_policy=ParentClosePolicy.ABANDON,
         )
 
-        # Parent continues without waiting for child completion
         return handle.id
 ```
-
+</AnnotatedCode>
 </TabItem>
 <TabItem value="go" label="Go">
-
+<AnnotatedCode
+  annotations={[
+    {
+      label: 'Parent Close Policy',
+      description:
+        'Controls what happens to the Child Workflow when the parent closes. ABANDON lets the child keep running after the parent completes.',
+      lines: [3],
+    },
+    {
+      label: 'Workflow Id',
+      description:
+        'Gives the Child Workflow a stable identity for tracking, querying, and deduplication in the UI.',
+      lines: [14],
+    },
+    {
+      label: 'Async start',
+      description:
+        'Starts the Child Workflow without waiting for it to finish. The parent continues after the child has started.',
+      lines: [7],
+    },
+  ]}
+>
 ```go
-// parent_workflow.go
-import (
-    enumspb "go.temporal.io/api/enums/v1"
-    "go.temporal.io/sdk/workflow"
-)
-
 func ParentWorkflow(ctx workflow.Context, input string) (string, error) {
     cwo := workflow.ChildWorkflowOptions{
         ParentClosePolicy: enumspb.PARENT_CLOSE_POLICY_ABANDON,
@@ -213,22 +247,40 @@ func ParentWorkflow(ctx workflow.Context, input string) (string, error) {
 
     childFuture := workflow.ExecuteChildWorkflow(ctx, ChildWorkflow, input)
 
-    // Wait for child to start, not complete
     var childWE workflow.Execution
     if err := childFuture.GetChildWorkflowExecution().Get(ctx, &childWE); err != nil {
         return "", err
     }
 
-    // Parent continues without waiting for child completion
     return childWE.ID, nil
 }
 ```
-
+</AnnotatedCode>
 </TabItem>
 <TabItem value="java" label="Java">
-
+<AnnotatedCode
+  annotations={[
+    {
+      label: 'Parent Close Policy',
+      description:
+        'Controls what happens to the Child Workflow when the parent closes. ABANDON lets the child keep running after the parent completes.',
+      lines: [6],
+    },
+    {
+      label: 'Workflow Id',
+      description:
+        'Gives the Child Workflow a stable identity for tracking, querying, and deduplication in the UI.',
+      lines: [5],
+    },
+    {
+      label: 'Async start',
+      description:
+        'Starts the Child Workflow without waiting for it to finish. The parent continues after the child has started.',
+      lines: [11],
+    },
+  ]}
+>
 ```java
-// ParentWorkflowImpl.java
 public class ParentWorkflowImpl implements ParentWorkflow {
   @Override
   public WorkflowExecution execute(String input) {
@@ -239,21 +291,39 @@ public class ParentWorkflowImpl implements ParentWorkflow {
 
     ChildWorkflow child = Workflow.newChildWorkflowStub(ChildWorkflow.class, options);
 
-    // Async call - returns immediately
     Async.function(child::processData, input);
 
-    // Get child execution info without waiting for completion
     Promise<WorkflowExecution> childExecution = Workflow.getWorkflowExecution(child);
-    return childExecution.get(); // Blocks only until child starts
+    return childExecution.get();
   }
 }
 ```
-
+</AnnotatedCode>
 </TabItem>
 <TabItem value="typescript" label="TypeScript">
-
+<AnnotatedCode
+  annotations={[
+    {
+      label: 'Parent Close Policy',
+      description:
+        'Controls what happens to the Child Workflow when the parent closes. ABANDON lets the child keep running after the parent completes.',
+      lines: [7],
+    },
+    {
+      label: 'Workflow Id',
+      description:
+        'Gives the Child Workflow a stable identity for tracking, querying, and deduplication in the UI.',
+      lines: [10],
+    },
+    {
+      label: 'Async start',
+      description:
+        'Starts the Child Workflow without waiting for it to finish. The parent continues after the child has started.',
+      lines: [5, 6, 7, 8],
+    },
+  ]}
+>
 ```typescript
-// workflows.ts
 import { startChild, ParentClosePolicy } from '@temporalio/workflow';
 import { childWorkflow } from './child-workflows';
 
@@ -263,12 +333,10 @@ export async function parentWorkflow(input: string): Promise<string> {
     parentClosePolicy: ParentClosePolicy.PARENT_CLOSE_POLICY_ABANDON,
   });
 
-  // Parent continues without waiting for child completion
-  // childHandle.workflowId and childHandle.firstExecutionRunId are available
   return childHandle.workflowId;
 }
 ```
-
+</AnnotatedCode>
 </TabItem>
 </Tabs>
 

docs/develop/environment-configuration.mdx

@@ -10,7 +10,7 @@ tags:
   - TOML
 ---
 
-import { SdkTabs } from '@site/src/components';
+import { SdkTabs, AnnotatedCode } from '@site/src/components';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -92,6 +92,48 @@ MIIPrivateKeyDataHere...
 -----END PRIVATE KEY-----"""
 ```
 
+Select a concept to highlight the matching connection settings in a Cloud profile:
+
+<AnnotatedCode
+  annotations={[
+    {
+      label: 'Address',
+      description:
+        'Temporal Service host and port. For Temporal Cloud, use your Namespace endpoint (for example your-namespace.account.tmprl.cloud:7233).',
+      lines: [2],
+    },
+    {
+      label: 'Namespace',
+      description:
+        'Namespace this Client connects to. On Temporal Cloud, include the account suffix when your tooling expects it.',
+      lines: [3],
+    },
+    {
+      label: 'API key',
+      description:
+        'Authenticates the Client to Temporal Cloud. Prefer environment variables for secrets in real deployments; TOML is fine for local profiles.',
+      lines: [4],
+    },
+    {
+      label: 'TLS',
+      description:
+        'Optional mTLS settings. TLS is often auto-enabled when an API key or TLS block is present; set certificate paths for mutual TLS.',
+      lines: [6, 7, 8],
+    },
+  ]}
+>
+```toml
+[profile.prod]
+address = "your-namespace.a1b2c.tmprl.cloud:7233"
+namespace = "your-namespace"
+api_key = "your-api-key-here"
+
+[profile.prod.tls]
+client_cert_path = "/etc/temporal/certs/client.pem"
+client_key_path = "/etc/temporal/certs/client.key"
+```
+</AnnotatedCode>
+
 The [`temporal cloud login`](/cli/cloud#interactive-login) command also writes to this file. When you run `temporal cloud login --profile prod`, the OAuth token is stored in the specified profile automatically. Subsequent commands that use that profile read the token from the TOML file to authenticate with Temporal Cloud.
 
 ## CLI integration