code-snippets

Skill: Code Snippets in Docs

Purpose

This skill describes how to reference code from sample repos in Agent Framework docs pages, eliminating inline code duplication.

:::code Directive Syntax

:::code language="python" source="~/../agent-framework-code/python/samples/01-get-started/01_hello_agent.py" id="create_agent" highlight="1-4":::

Parameters

Source Path Conventions

• In-repo snippets: ~/agent-framework/<path-to-file>
• Out-of-repo snippets (dependent repositories): ~/../<path_to_root>/<path-to-file>
• Agent Framework code samples in this repo: ~/../agent-framework-code/python/samples/<section>/<file>.py

Out-of-repo snippet references

If the code file you want to reference is in a different repository, set up that code repository as a dependent repository in .openpublishing.publish.config.json. The path_to_root you assign acts like a folder name for snippet source paths.

Dependent repositories metadata

The dependent_repositories list is required in .openpublishing.publish.config.json for cross-repository references (CRR):

{
  "dependent_repositories": [
    {
      "path_to_root": "<relative path to repository root>",
      "url": "<referenced repository url>",
      "branch": "<branch name of referenced repository>",
      "branch_mapping": {
        "<source repository branch>": "<referenced repository branch>",
        "<source repository branch>": "<referenced repository branch>"
      }
    },
    {
      "path_to_root": "token",
      "url": "https://github.com/Microsoft/token",
      "branch": "main",
      "branch_mapping": {
        "main": "main",
        "develop": "test"
      }
    }
  ]
}

Snippet reference syntax

Use the same :::code syntax for CRR snippets as in-repo snippets. Only the source path changes.

• Start paths with ~ for docset-root-relative references.
• Use .. segments to move up directories when needed (for example ../../).
• Prefer readable paths; deeply nested .. chains are harder to maintain.

Example CRR source path:

~/../xamarin-forms-samples/WebServices/TodoREST/TodoAPI/TodoAPI/Startup.cs

[!NOTE] The dependent repository alias is rooted at repo root, but ~ is rooted at the docset's build_source_folder. In this repo, Agent Framework docs use "build_source_folder": "agent-framework", so dependent repositories are referenced like ~/../agent-framework-code/....

[!IMPORTANT] Updating an external code snippet does not automatically trigger a content build. Trigger a build by changing doc content or starting a build manually.

Snippet Tags in Source Files

Python

# <create_agent>
client = OpenAIResponsesClient(...)
agent = client.as_agent(name="...", instructions="...")
# </create_agent>

C#

// <create_agent>
var agent = await client.CreateAIAgentAsync(...);
// </create_agent>

Rules

• Tag names use snake_case
• Tags must be unique within a file
• Tags cannot overlap or nest
• Keep snippet regions small and focused (5-20 lines ideal)
• Include all necessary imports within the snippet OR document them separately

Zone Pivots

Every page showing code for both languages uses zone pivots:

:::zone pivot="programming-language-csharp"
:::code language="csharp" source="~/../agent-framework-code/dotnet/samples/..." id="...":::
:::zone-end

:::zone pivot="programming-language-python"
:::code language="python" source="~/../agent-framework-code/python/samples/..." id="...":::
:::zone-end

When to Apply This Skill

Apply :::code references when:

1. The sample repo structure is stable (samples merged to main)
2. The sample file has proper snippet tags
3. You want to eliminate inline code duplication

Until then, use inline code blocks (python / csharp) as a temporary measure.

Common Snippet IDs

Reference

• MS Learn code-in-docs guide