Skip to content

Commit b15e285

Browse files
sunbryeCopilot
andcommitted
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>
1 parent 70f796c commit b15e285

1 file changed

Lines changed: 64 additions & 0 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+
```

0 commit comments

Comments
 (0)