Skip to content

Commit c638a5e

Browse files
sunbryeCopilotCopilotscottaddie
authored
Sunbrye/fix azure managed identity tabs (#1801)
* Restructure azure-managed-identity for codetabs compatibility Move shared prose (prerequisites heading, usage description) outside details blocks. Each details block now contains only code, which allows the docs-internal normalization pipeline to convert them into codetabs correctly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add multi-language code examples guidance to docs style guide Document the correct format for <details> blocks so they convert cleanly to codetabs in the docs-internal normalization pipeline. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix prose wording and nested fences in style guide examples Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com> * Switch style guide examples back to code fences (4-backtick outer fence) Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com> * Use 3-backtick fences for style guide markdown examples Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com>
1 parent ef2bb93 commit c638a5e

2 files changed

Lines changed: 134 additions & 63 deletions

File tree

‎.github/instructions/docs-style.instructions.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,3 +160,67 @@ Body text here.
160160

161161
* [Link text](./relative-path.md): short description
162162
```
163+
164+
## Multi-language code examples
165+
166+
When showing the same concept in multiple programming languages, use consecutive `<details>` blocks. The docs-internal normalization pipeline converts these into tabbed language switchers on docs.github.com.
167+
168+
### Rules
169+
170+
* **Only code inside `<details>` blocks.** Shared prose, headings, and explanations must go outside the blocks. Each block should contain only a code fence (and optionally a `<!-- docs-validate: skip -->` comment).
171+
* **Blocks must be consecutive.** No content (headings, paragraphs) between `<details>` blocks in the same group. Blank lines between blocks are fine.
172+
* **Use the exact `<summary>` format:** `<summary><strong>LANGUAGE</strong></summary>`. Supported labels: `.NET`, `Python`, `TypeScript`, `Go`, `Java`, `Rust`, `Node.js`, `Shell`.
173+
* **Need 2+ blocks to form a group.** A single `<details>` block won't be converted and renders as raw HTML on docs.github.com.
174+
* **Equal content across tabs.** Each tab should show the same concept in a different language. Language-specific extras should be a separate section outside the tabs.
175+
176+
### Correct
177+
178+
Shared prose goes above the group, then each `<details>` block contains only code:
179+
180+
```markdown
181+
Install the SDK:
182+
183+
<details open>
184+
<summary><strong>.NET</strong></summary>
185+
186+
<!-- docs-validate: skip -->
187+
188+
```bash
189+
dotnet add package GitHub.Copilot.SDK
190+
```
191+
192+
</details>
193+
<details>
194+
<summary><strong>Python</strong></summary>
195+
196+
<!-- docs-validate: skip -->
197+
198+
```bash
199+
pip install github-copilot-sdk
200+
```
201+
202+
</details>
203+
```
204+
205+
### Incorrect
206+
207+
Do not put headings, prose, or multiple sections inside a `<details>` block:
208+
209+
```markdown
210+
<details>
211+
<summary><strong>Python</strong></summary>
212+
213+
### Prerequisites ← breaks TOC/anchors
214+
Install the packages: ← prose belongs outside
215+
216+
```bash
217+
pip install github-copilot-sdk
218+
```
219+
220+
### Basic usage ← multiple sections in one tab
221+
```python
222+
[code]
223+
```
224+
225+
</details>
226+
```

‎docs/setup/azure-managed-identity.md‎

Lines changed: 70 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -29,20 +29,49 @@ sequenceDiagram
2929

3030
## Code samples
3131

32+
### Prerequisites
33+
34+
Install the Azure Identity and Copilot SDK packages for your language:
35+
3236
<details open>
3337
<summary><strong>.NET</strong></summary>
3438

35-
### Prerequisites
36-
37-
Install the required packages:
39+
<!-- docs-validate: skip -->
3840

3941
```bash
4042
dotnet add package GitHub.Copilot.SDK
4143
dotnet add package Azure.Core
4244
```
4345

46+
</details>
47+
<details>
48+
<summary><strong>Python</strong></summary>
49+
50+
<!-- docs-validate: skip -->
51+
52+
```bash
53+
pip install github-copilot-sdk azure-identity
54+
```
55+
56+
</details>
57+
<details>
58+
<summary><strong>TypeScript</strong></summary>
59+
60+
<!-- docs-validate: skip -->
61+
62+
```bash
63+
npm install @github/copilot-sdk @azure/identity
64+
```
65+
66+
</details>
67+
4468
### Basic usage
4569

70+
Get a token using `DefaultAzureCredential` and pass it as the bearer token in your provider configuration:
71+
72+
<details open>
73+
<summary><strong>.NET</strong></summary>
74+
4675
<!-- docs-validate: skip -->
4776

4877
```csharp
@@ -76,20 +105,9 @@ Console.WriteLine(response?.Data.Content);
76105
```
77106

78107
</details>
79-
80108
<details>
81109
<summary><strong>Python</strong></summary>
82110

83-
### Prerequisites
84-
85-
Install the required packages:
86-
87-
```bash
88-
pip install github-copilot-sdk azure-identity
89-
```
90-
91-
### Basic usage
92-
93111
<!-- docs-validate: skip -->
94112

95113
```python
@@ -133,9 +151,46 @@ async def main():
133151
asyncio.run(main())
134152
```
135153

154+
</details>
155+
<details>
156+
<summary><strong>TypeScript</strong></summary>
157+
158+
<!-- docs-validate: skip -->
159+
160+
```typescript
161+
import { DefaultAzureCredential } from "@azure/identity";
162+
import { CopilotClient } from "@github/copilot-sdk";
163+
164+
const credential = new DefaultAzureCredential({
165+
requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"],
166+
});
167+
const tokenResponse = await credential.getToken(
168+
"https://ai.azure.com/.default"
169+
);
170+
171+
const client = new CopilotClient();
172+
173+
const session = await client.createSession({
174+
model: "gpt-5.5",
175+
provider: {
176+
type: "openai",
177+
baseUrl: `${process.env.FOUNDRY_RESOURCE_URL}/openai/v1/`,
178+
bearerToken: tokenResponse.token,
179+
wireApi: "responses",
180+
},
181+
});
182+
183+
const response = await session.sendAndWait({ prompt: "Hello!" });
184+
console.log(response?.data.content);
185+
186+
await client.stop();
187+
```
188+
189+
</details>
190+
136191
### Token refresh for long-running applications
137192

138-
Bearer tokens expire (typically after ~1 hour). For servers or long-running agents, refresh the token before creating each session:
193+
Bearer tokens expire (typically after ~1 hour). For servers or long-running agents, refresh the token before creating each session. The following Python example demonstrates this pattern:
139194

140195
<!-- docs-validate: skip -->
141196

@@ -181,54 +236,6 @@ class ManagedIdentityCopilotAgent:
181236
return response.data.content if response else ""
182237
```
183238

184-
</details>
185-
186-
<details>
187-
<summary><strong>TypeScript</strong></summary>
188-
189-
### Prerequisites
190-
191-
Install the required packages:
192-
193-
```bash
194-
npm install @github/copilot-sdk @azure/identity
195-
```
196-
197-
### Basic usage
198-
199-
<!-- docs-validate: skip -->
200-
201-
```typescript
202-
import { DefaultAzureCredential } from "@azure/identity";
203-
import { CopilotClient } from "@github/copilot-sdk";
204-
205-
const credential = new DefaultAzureCredential({
206-
requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"],
207-
});
208-
const tokenResponse = await credential.getToken(
209-
"https://ai.azure.com/.default"
210-
);
211-
212-
const client = new CopilotClient();
213-
214-
const session = await client.createSession({
215-
model: "gpt-5.5",
216-
provider: {
217-
type: "openai",
218-
baseUrl: `${process.env.FOUNDRY_RESOURCE_URL}/openai/v1/`,
219-
bearerToken: tokenResponse.token,
220-
wireApi: "responses",
221-
},
222-
});
223-
224-
const response = await session.sendAndWait({ prompt: "Hello!" });
225-
console.log(response?.data.content);
226-
227-
await client.stop();
228-
```
229-
230-
</details>
231-
232239
## Environment configuration
233240

234241
| Variable | Description | Example |

0 commit comments

Comments
 (0)