annotated code component

MARKDOWN_PIPELINE.md

@@ -122,7 +122,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

@@ -11,7 +11,7 @@ tags:
 ---
 
 import { LANGUAGE_TAB_GROUP, getLanguageLabel } from '@site/src/constants/languageTabs';
-import { SdkTabs } from '@site/src/components';
+import { SdkTabs, AnnotatedCode } from '@site/src/components';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -93,6 +93,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