You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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>
Copy file name to clipboardExpand all lines: .github/instructions/docs-style.instructions.md
+64Lines changed: 64 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -160,3 +160,67 @@ Body text here.
160
160
161
161
*[Link text](./relative-path.md): short description
162
162
```
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.
***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
+
<detailsopen>
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:
0 commit comments