Sunbrye/fix azure managed identity tabs#1801
Merged
Merged
Conversation
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>
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>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Copilot SDK documentation to ensure multi-language examples render correctly after the docs-internal normalization pipeline converts consecutive <details> blocks into tabbed code switchers, and it documents the required authoring pattern in the docs style guide.
Changes:
- Restructures
docs/setup/azure-managed-identity.mdso each<details>tab contains only a single code fence and shared prose/headings live outside the tabs. - Splits examples into two consecutive-tab groups (prerequisites and basic usage) and pulls the Python-only token refresh guidance out of tabs.
- Adds a “Multi-language code examples” section to the docs style guide describing the required
<details>structure and giving correct/incorrect patterns.
Show a summary per file
| File | Description |
|---|---|
| docs/setup/azure-managed-identity.md | Refactors multi-language samples into consecutive <details> groups so they normalize into stable code tabs and preserve TOC/anchors. |
| .github/instructions/docs-style.instructions.md | Documents the required <details>-tabs authoring rules for multi-language examples to prevent future normalization breakage. |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 4
Comment on lines
+180
to
+203
| ```markdown | ||
| Install the SDK: | ||
|
|
||
| <details open> | ||
| <summary><strong>.NET</strong></summary> | ||
|
|
||
| <!-- docs-validate: skip --> | ||
|
|
||
| ```bash | ||
| dotnet add package GitHub.Copilot.SDK | ||
| ``` | ||
|
|
||
| </details> | ||
| <details> | ||
| <summary><strong>Python</strong></summary> | ||
|
|
||
| <!-- docs-validate: skip --> | ||
|
|
||
| ```bash | ||
| pip install github-copilot-sdk | ||
| ``` | ||
|
|
||
| </details> | ||
| ``` |
Comment on lines
+209
to
+226
| ```markdown | ||
| <details> | ||
| <summary><strong>Python</strong></summary> | ||
|
|
||
| ### Prerequisites ← breaks TOC/anchors | ||
| Install the packages: ← prose belongs outside | ||
|
|
||
| ```bash | ||
| pip install github-copilot-sdk | ||
| ``` | ||
|
|
||
| ### Basic usage ← multiple sections in one tab | ||
| ```python | ||
| [code] | ||
| ``` | ||
|
|
||
| </details> | ||
| ``` |
scottaddie
approved these changes
Jun 25, 2026
Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com>
scottaddie
reviewed
Jun 25, 2026
| Shared prose goes above the group, then each `<details>` block contains only code: | ||
|
|
||
| ```markdown | ||
| ~~~markdown |
Contributor
There was a problem hiding this comment.
@copilot Switch back to code fences for the markdown blocks
Contributor
There was a problem hiding this comment.
Done in 81e8bf1. Used 4-backtick outer fences (````markdown) so the inner 3-backtick fences render correctly.
Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com>
Co-authored-by: scottaddie <10702007+scottaddie@users.noreply.github.com>
scottaddie
approved these changes
Jun 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The current
<details>block structure inazure-managed-identity.mdputs headings, prose, and multiple code blocks inside each tab. When the docs-internal normalization pipeline converts these to{% codetabs %}, this structure breaks headings don't render in the TOC, anchor links break, and the tabs contain unequal amounts of content.This also adds documentation to the style guide so future authors know the correct format.
What's changed
1. Restructured
docs/setup/azure-managed-identity.md<details>blocks<details>block now contains only a code fence no headings, no paragraphs2. Added guidance to
.github/instructions/docs-style.instructions.mdNew "Multi-language code examples" section documenting:
<details>blocks<summary>format requiredPreview
Before
After
cc @scottaddie