# 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 ``, run the relevant `npm run docs:` 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 `
` blocks. The docs-internal normalization pipeline converts these into tabbed language switchers on docs.github.com. ### Rules * **Only code inside `
` blocks.** Shared prose, headings, and explanations must go outside the blocks. Each block should contain only a code fence (and optionally a `` comment). * **Blocks must be consecutive.** No content (headings, paragraphs) between `
` blocks in the same group. Blank lines between blocks are fine. * **Use the exact `` format:** `LANGUAGE`. Supported labels: `.NET`, `Python`, `TypeScript`, `Go`, `Java`, `Rust`, `Node.js`, `Shell`. * **Need 2+ blocks to form a group.** A single `
` 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 `
` block contains only code: ```markdown Install the SDK:
.NET ```bash dotnet add package GitHub.Copilot.SDK ```
Python ```bash pip install github-copilot-sdk ```
``` ### Incorrect Do not put headings, prose, or multiple sections inside a `
` block: ```markdown
Python ### 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] ```
```