Add Extensibility section to encyclopedia (#4314)

drewhoskins-temporal · lennessyy · web-flow · commit cc24b98a4085 · 2026-03-24T17:03:45.000Z
* Improve legibility of Golang context propagation docs

* Links to context propagation docs from outside

* Extensibility section of Encyclopedia

---------

Co-authored-by: Lenny Chen &lt;55669665+lennessyy@users.noreply.github.com&gt;
diff --git a/docs/develop/plugins-guide.mdx b/docs/develop/plugins-guide.mdx
@@ -36,9 +36,6 @@ Here are some common use cases for plugins:
 The recommended way to start building plugins is with a `SimplePlugin`. This abstraction will tackle the vast majority
 of plugins people want to write.
 
-For advanced use cases, you can extend the methods in lower-level classes that Simple Plugin is based on without
-re-implementing what you’ve done. See the [Advanced Topics section](#advanced-topics-for-plugins) for more information.
-
 ### Example Plugins
 
 If you prefer to learn by getting hands-on with code, check out some existing plugins.
@@ -60,6 +57,7 @@ do.
 - [Built-in Nexus Operations](#built-in-nexus-operations)
 - [Custom Data Converters](#custom-data-converters)
 - [Interceptors](#interceptors)
+- [Context Propagators](#context-propagators)
 
 ### Built-in Activity
 
@@ -784,6 +782,27 @@ plugin = Temporalio::SimplePlugin.new(
   </SdkTabs.Ruby>
 </SdkTabs>
 
+### Context Propagators {#context-propagators}
+
+Context propagators pass custom key-value data (such as tracing IDs, tenant IDs, or auth tokens) across Workflow, Activity, and Child Workflow boundaries via Temporal headers. See [Context Propagation](/encyclopedia/context-propagation) for details on how they work.
+
+Propagators registered via a Plugin are appended to any propagators already set by the user or by previous plugins.
+
+<SdkTabs hideUnsupportedLanguages>
+  <SdkTabs.Go>
+
+```go
+func createContextPropagatorPlugin() (*temporal.SimplePlugin, error) {
+    return temporal.NewSimplePlugin(temporal.SimplePluginOptions{
+        Name:               "organization.PluginName",
+        ContextPropagators: []workflow.ContextPropagator{NewMyPropagator()},
+    })
+}
+```
+
+  </SdkTabs.Go>
+</SdkTabs>
+
 ### Special considerations for different languages
 
 Each of the SDKs has nuances you should be aware of so you can account for it in your code.
diff --git a/docs/encyclopedia/context-propagation.mdx b/docs/encyclopedia/context-propagation.mdx
@@ -0,0 +1,32 @@
+---
+id: context-propagation
+title: Context Propagation
+sidebar_label: Context Propagation
+description: Pass custom key-value data across Workflow, Activity, and Child Workflow boundaries using Temporal headers.
+toc_max_heading_level: 4
+keywords:
+  - context propagation
+  - context propagators
+  - headers
+  - tracing
+  - observability
+tags:
+  - Concepts
+  - Observability
+---
+
+Context propagation lets you pass custom key-value data from a Client to Workflows, and from Workflows to Activities and Child Workflows, without threading values through every function signature.
+
+Common use cases:
+
+- Propagating distributed tracing IDs (e.g., OpenTelemetry trace context)
+- Passing tenant IDs for multi-tenant applications
+- Forwarding auth tokens or request-scoped metadata
+
+Each SDK provides a **context propagator** interface you implement to control which values are injected and extracted. You register propagators on the Client, and the SDK calls them automatically at every boundary.
+
+## Implementing Context Propagation
+
+Here are SDK-specific guides:
+
+- [Go](/develop/go/observability#context-propagation)
diff --git a/docs/encyclopedia/extensibility.mdx b/docs/encyclopedia/extensibility.mdx
@@ -0,0 +1,23 @@
+---
+id: extensibility
+title: Extensibility
+sidebar_label: Extensibility
+description: Temporal offers mechanisms to augment the functionality of Workflows and Activities, including data conversion, context propagation, interceptors, and plugins.
+toc_max_heading_level: 4
+keywords:
+  - extensibility
+  - interceptors
+  - context propagation
+  - data conversion
+  - plugins
+tags:
+  - Concepts
+---
+
+Temporal offers many mechanisms to augment the functionality of Workflows and Activities.
+These allow you to customize how data is serialized, propagate metadata across execution boundaries, and inject cross-cutting behavior like tracing and logging.
+
+- [Data Conversion](/dataconversion) - Customize how arguments and return values are serialized, compressed, or encrypted
+- [Context Propagation](/encyclopedia/context-propagation) - Pass custom metadata (tracing IDs, tenant IDs, auth tokens) across Workflow, Activity, and Child Workflow boundaries
+- [Interceptors](/encyclopedia/interceptors) - Add cross-cutting behavior (observability, authorization, header manipulation) before and after SDK operations
+- [Plugins](/encyclopedia/plugins) - Bundle interceptors, context propagators, data converters, and built-in definitions into reusable packages
diff --git a/docs/encyclopedia/index.mdx b/docs/encyclopedia/index.mdx
@@ -24,7 +24,7 @@ The following Encyclopedia pages describe the concepts, components, and features
 - [Temporal Service](/temporal-service)
 - [Namespaces](/namespaces)
 - [Temporal Nexus](/nexus)
-- [Data conversion](/dataconversion)
+- [Extensibility](/encyclopedia/extensibility)
 
 For a complete list of Temporal terms, see the [Glossary](/glossary).
 
diff --git a/docs/encyclopedia/interceptors.mdx b/docs/encyclopedia/interceptors.mdx
@@ -0,0 +1,30 @@
+---
+id: interceptors
+title: Interceptors
+sidebar_label: Interceptors
+description: Add cross-cutting behavior like observability, authorization, and header manipulation before and after SDK operations.
+toc_max_heading_level: 4
+keywords:
+  - interceptors
+  - middleware
+  - observability
+  - tracing
+tags:
+  - Concepts
+---
+
+Interceptors let you add cross-cutting behavior before and after SDK operations such as starting a Workflow, executing an Activity, or handling a Signal. They work like middleware: each interceptor wraps the next, forming a chain that executes around the underlying operation.
+
+Common use cases:
+
+- Observability (logging, metrics, tracing)
+- Authorization and authentication checks
+- Header manipulation (propagating metadata)
+- Input/output validation
+
+## Implementing Interceptors
+
+Here are SDK-specific guides:
+
+- [Python](/develop/python/interceptors)
+- [TypeScript](/develop/typescript/interceptors)
diff --git a/docs/encyclopedia/plugins.mdx b/docs/encyclopedia/plugins.mdx
@@ -0,0 +1,26 @@
+---
+id: plugins
+title: Plugins
+sidebar_label: Plugins
+description: Bundle interceptors, context propagators, data converters, and built-in definitions into reusable packages.
+toc_max_heading_level: 4
+keywords:
+  - plugins
+  - simple plugin
+  - extensibility
+tags:
+  - Concepts
+---
+
+A Plugin bundles multiple extensibility primitives - interceptors, context propagators, data converters, and built-in Workflow/Activity/Nexus definitions - into a single reusable package. Plugins let platform teams and library authors ship ready-made functionality that application developers can adopt with a single registration call.
+
+Common use cases:
+
+- AI Agent SDKs (e.g., OpenAI Agents, Pydantic AI)
+- Observability packages (tracing, logging, metrics)
+- Encryption or compliance middleware
+- Shared infrastructure integrations (messaging, payments, LLM calls)
+
+## Implementing Plugins
+
+See the [Plugins guide](/develop/plugins-guide) for how to build and use plugins across all supported SDKs.
diff --git a/sidebars.js b/sidebars.js
@@ -855,20 +855,34 @@ module.exports = {
         },
         {
           type: 'category',
-          label: 'Data Conversion',
+          label: 'Extensibility',
           collapsed: true,
           link: {
             type: 'doc',
-            id: 'encyclopedia/data-conversion/dataconversion',
+            id: 'encyclopedia/extensibility',
           },
           items: [
-            'encyclopedia/data-conversion/default-custom-data-converters',
-            'encyclopedia/data-conversion/payload-converter',
-            'encyclopedia/data-conversion/payload-codec',
-            'encyclopedia/data-conversion/failure-converter',
-            'encyclopedia/data-conversion/remote-data-encoding',
-            'encyclopedia/data-conversion/codec-server',
-            'encyclopedia/data-conversion/key-management',
+            {
+              type: 'category',
+              label: 'Data Conversion',
+              collapsed: true,
+              link: {
+                type: 'doc',
+                id: 'encyclopedia/data-conversion/dataconversion',
+              },
+              items: [
+                'encyclopedia/data-conversion/default-custom-data-converters',
+                'encyclopedia/data-conversion/payload-converter',
+                'encyclopedia/data-conversion/payload-codec',
+                'encyclopedia/data-conversion/failure-converter',
+                'encyclopedia/data-conversion/remote-data-encoding',
+                'encyclopedia/data-conversion/codec-server',
+                'encyclopedia/data-conversion/key-management',
+              ],
+            },
+            'encyclopedia/context-propagation',
+            'encyclopedia/interceptors',
+            'encyclopedia/plugins',
           ],
         },
         'web-ui',
