From 5c032c666cdf360383eed191cafdea597cbbf0d3 Mon Sep 17 00:00:00 2001 From: sunbrye Date: Fri, 8 May 2026 11:02:32 -0700 Subject: [PATCH 1/3] Add docs style instructions for copilot agents Add .github/instructions/docs-style.instructions.md scoped to docs/** with style rules aligned to docs.github.com conventions. Covers headings, callouts, lists, em dashes, code snippets, and more. Add reference in .github/copilot-instructions.md so agents know the docs instructions exist. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 1 + .../instructions/docs-style.instructions.md | 162 ++++++++++++++++++ 2 files changed, 163 insertions(+) create mode 100644 .github/instructions/docs-style.instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 098e1a70c..68c29b66e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -14,6 +14,7 @@ - Test harness & E2E: `test/harness/*`, Python harness wrapper `python/e2e/testharness/proxy.py` - Schemas & type generation: `nodejs/scripts/generate-session-types.ts` - Session snapshots used by E2E: `test/snapshots/` (used by the replay proxy) +- Docs style guide: `.github/instructions/docs-style.instructions.md` (used for `docs/**`) ## Developer workflows (commands you’ll use often) ▶️ diff --git a/.github/instructions/docs-style.instructions.md b/.github/instructions/docs-style.instructions.md new file mode 100644 index 000000000..c78053300 --- /dev/null +++ b/.github/instructions/docs-style.instructions.md @@ -0,0 +1,162 @@ +--- +applyTo: "docs/**" +--- + +# 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: Azure AI Foundry` — not `## Quick Start: Azure AI 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, Azure AD, 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 a single `Data` class/struct with all fields optional. +``` + +## 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 `---` horizontal rules as section dividers. Use headings to separate sections. + +## 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 + +* Do not modify code block contents. The SDK team's `docs-validate` workflow validates all code examples. + +## 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 +``` From 88a63f0c287099fb68636f6413f4074efd40c456 Mon Sep 17 00:00:00 2001 From: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com> Date: Fri, 8 May 2026 11:09:57 -0700 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .github/instructions/docs-style.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/docs-style.instructions.md b/.github/instructions/docs-style.instructions.md index c78053300..974dc02a9 100644 --- a/.github/instructions/docs-style.instructions.md +++ b/.github/instructions/docs-style.instructions.md @@ -100,7 +100,7 @@ If you are writing a new section with substantive content, create a named file ( ## Code snippets -* Do not modify code block contents. The SDK team's `docs-validate` workflow validates all code examples. +* Only modify code block contents when necessary. Keep all examples passing the SDK team's `docs-validate` workflow, rerun validation after changes, and use `docs-validate: skip` or `docs-validate: hidden` markers when appropriate. ## Voice and tone From 4ac0405bd9c4c21c1a4e590161e60ae0bd689ce8 Mon Sep 17 00:00:00 2001 From: sunbrye Date: Fri, 8 May 2026 11:12:01 -0700 Subject: [PATCH 3/3] updates --- .github/instructions/docs-style.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/docs-style.instructions.md b/.github/instructions/docs-style.instructions.md index 974dc02a9..36ad72015 100644 --- a/.github/instructions/docs-style.instructions.md +++ b/.github/instructions/docs-style.instructions.md @@ -90,7 +90,7 @@ The SDK is a transport layer—it sends your prompt to the CLI over JSON-RPC. ## Horizontal rules -Do not use `---` horizontal rules as section dividers. Use headings to separate sections. +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