copilot-sdk

# Copilot SDK docs style guide

This style guide applies to all documentation in the `docs/` directory. These docs are synced to `github/docs-internal` via a normalization pipeline, so they must follow the conventions below to be compatible with docs.github.com.

## Headings

Use **sentence case** for all headings. Capitalize only the first word and proper nouns.

* `## Quick start: Microsoft Foundry` — not `## Quick Start: Microsoft Foundry`
* `# Custom agents and sub-agent orchestration` — not `# Custom Agents & Sub-Agent Orchestration`

Use `and` instead of `&` in headings.

Do not use `**bold**` or `*italic*` markers inside headings. The heading level provides emphasis.

### Proper nouns to always capitalize

* Products/companies: GitHub, Copilot, Azure, OpenAI, Anthropic, Microsoft, Ollama, Slack, Foundry, Kubernetes, Docker
* Languages/frameworks: TypeScript, JavaScript, Python, Java, Node.js, OpenTelemetry, Express
* Platforms: macOS, Linux, Windows
* Protocols/formats: OAuth, JSON-RPC, JSON, YAML, HTTP, TCP, SSE, REST
* Acronyms: MCP, BYOK, MAF, SDK, CLI, API, HMAC, CI/CD, SaaS, ISV, FAQ, LLM, AI, EMU, ID, UI, PNG
* Tools (keep canonical casing): npm, npx, stdio
* Code identifiers in headings: SessionConfig, MessageOptions, TelemetryConfig, ProviderConfig, CopilotClient
* Multi-word proper names: GitHub App, GitHub Actions, GitHub OAuth, Foundry Local, Managed Identity, Container Instances

## Callouts

Use GitHub-flavored alert syntax:

```markdown
> [!NOTE]
> This is a note.

> [!TIP]
> This is a tip.

> [!WARNING]
> This is a warning.
```

Never use `> **Note:**` or `> **Tip:**` style callouts.

When a callout applies to a specific language, put the qualifier as bold text in the body:

```markdown
> [!TIP]
> **(Python / Go)** These SDKs use separate, per-event data types.
```

## Lists

### Unordered lists

Use `*` (asterisks) for unordered list markers, not `-` (hyphens).

### Ordered lists

Use `1.` for every item in ordered lists, not sequential numbering. This makes reordering easier.

```markdown
1. First step
1. Second step
1. Third step
```

### List item formatting

* Capitalize the first letter of each list item.
* Use periods only if the item is a complete sentence.
* Introduce lists with a descriptive sentence, not vague phrases like "the following" in isolation.

## Em dashes

For list items with a **label and description**, use a colon:

```markdown
* **Ephemeral**: not persisted to disk, not replayed on session resume
```

For em dashes used mid-sentence, use no spaces:

```markdown
The SDK is a transport layer—it sends your prompt to the CLI over JSON-RPC.
```

## Horizontal rules

Do not use `---` as a horizontal rule to visually separate sections in the body of an article. Use headings to separate sections instead. This does not apply to YAML frontmatter delimiters.

## Index.md files

In the docs pipeline, `index.md` files become YAML-only category pages. Rich content (prose, code samples, diagrams) must live in standalone files.

If you are writing a new section with substantive content, create a named file (for example, `choosing-a-setup-path.md`) rather than putting the content in `index.md`.

## Code snippets

* Only modify code block contents when necessary. From `<SDK_ROOT>`, run the
  relevant `npm run docs:<language>` validator for Node.js, Python, Go, .NET,
  or Java. Rust has no `docs:rust` facade; validate its API documentation with
  `cd rust && DOCS_RS=1 cargo doc --no-deps --all-features` and follow
  `rust/README.md`. Keep using `docs-validate: skip` or
  `docs-validate: hidden` markers when appropriate.

## Voice and tone

* Use clear, simple language approachable for a wide range of readers.
* Use active voice whenever possible.
* Avoid idioms, slang, and region-specific phrases.
* Avoid ambiguous modal verbs ("may", "might", "should", "could") when an action is required. Use definitive verbs instead.
* Refer to people as "people" or "users", not "customers."

## Emphasis

* Use **bold** for UI elements and for emphasis, sparingly (no more than five contiguous words).
* Do not bold text that already has other formatting (for example, all-caps placeholders).

## Word choice

| Use | Avoid |
|---|---|
| terminal | shell |
| sign in | log in, login |
| sign up | signup |
| email | e-mail |
| press (a key) | hit, tap |
| repository | repo |
| administrator | admin |
| for example | e.g. |
| and similar | etc. |

## What the pipeline handles

Authors do not need to worry about these — the normalization pipeline handles them automatically:

* YAML frontmatter (added to files for docs.github.com)
* Mermaid diagram → PNG conversion
* Link rewriting for docs.github.com cross-references
* Liquid variable substitution (product names)
* `[AUTOTITLE]` link conversion

## New article template

When creating a new docs article, use this structure:

```markdown
# Article title in sentence case

A one- or two-sentence intro explaining what the reader will learn or accomplish.

## First section

Body text here.

## Second section

Body text here.

## Further reading

* [Link text](./relative-path.md): short description
```

## Multi-language code examples

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.

### Rules

* **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).
* **Blocks must be consecutive.** No content (headings, paragraphs) between `<details>` blocks in the same group. Blank lines between blocks are fine.
* **Use the exact `<summary>` format:** `<summary><strong>LANGUAGE</strong></summary>`. Supported labels: `.NET`, `Python`, `TypeScript`, `Go`, `Java`, `Rust`, `Node.js`, `Shell`.
* **Need 2+ blocks to form a group.** A single `<details>` block won't be converted and renders as raw HTML on docs.github.com.
* **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.

### Correct

Shared prose goes above the group, then each `<details>` block contains only code:

```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>
```

### Incorrect

Do not put headings, prose, or multiple sections inside a `<details>` block:

```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>
```