Use `title` for configuration code fences in ty reference documentation

crates/ruff_dev/src/generate_ty_options.rs

@@ -166,8 +166,9 @@ fn emit_field(output: &mut String, name: &str, field: &OptionField, parents: &[S
     output.push('\n');
     let _ = writeln!(output, "**Type**: `{}`", field.value_type);
     output.push('\n');
-    output.push_str("**Example usage** (`pyproject.toml`):\n\n");
+    output.push_str("**Example usage**:\n\n");
     output.push_str(&format_example(
+        "pyproject.toml",
         &format_header(
             field.scope,
             field.example,
@@ -179,11 +180,11 @@ fn emit_field(output: &mut String, name: &str, field: &OptionField, parents: &[S
     output.push('\n');
 }
 
-fn format_example(header: &str, content: &str) -> String {
+fn format_example(title: &str, header: &str, content: &str) -> String {
     if header.is_empty() {
-        format!("```toml\n{content}\n```\n",)
+        format!("```toml title=\"{title}\"\n{content}\n```\n",)
     } else {
-        format!("```toml\n{header}\n{content}\n```\n",)
+        format!("```toml title=\"{title}\"\n{header}\n{content}\n```\n",)
     }
 }
 

crates/ty/docs/configuration.md

@@ -18,9 +18,9 @@ Valid severities are:
 
 **Type**: `dict[RuleName, "ignore" | "warn" | "error"]`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.rules]
 possibly-unresolved-reference = "warn"
 division-by-zero = "ignore"
@@ -45,9 +45,9 @@ configuration setting.
 
 **Type**: `list[str]`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.environment]
 extra-paths = ["./shared/my-search-path"]
 ```
@@ -76,9 +76,9 @@ This option can be used to point to virtual or system Python environments.
 
 **Type**: `str`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.environment]
 python = "./custom-venv-location/.venv"
 ```
@@ -103,9 +103,9 @@ If no platform is specified, ty will use the current platform:
 
 **Type**: `"win32" | "darwin" | "android" | "ios" | "linux" | "all" | str`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.environment]
 # Tailor type stubs and conditionalized type definitions to windows.
 python-platform = "win32"
@@ -137,9 +137,9 @@ to reflect the differing contents of the standard library across Python versions
 
 **Type**: `"3.7" | "3.8" | "3.9" | "3.10" | "3.11" | "3.12" | "3.13" | "3.14" | <major>.<minor>`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.environment]
 python-version = "3.12"
 ```
@@ -165,9 +165,9 @@ it will also be included in the first party search path.
 
 **Type**: `list[str]`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.environment]
 # Multiple directories (priority order)
 root = ["./src", "./lib", "./vendor"]
@@ -185,9 +185,9 @@ bundled as a zip file in the binary
 
 **Type**: `str`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.environment]
 typeshed = "/path/to/custom/typeshed"
 ```
@@ -240,9 +240,9 @@ If not specified, defaults to `[]` (excludes no files).
 
 **Type**: `list[str]`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [[tool.ty.overrides]]
 exclude = [
     "generated",
@@ -268,9 +268,9 @@ If not specified, defaults to `["**"]` (matches all files).
 
 **Type**: `list[str]`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [[tool.ty.overrides]]
 include = [
     "src",
@@ -292,9 +292,9 @@ severity levels or disable them entirely.
 
 **Type**: `dict[RuleName, "ignore" | "warn" | "error"]`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [[tool.ty.overrides]]
 include = ["src"]
 
@@ -358,9 +358,9 @@ to re-include `dist` use `exclude = ["!dist"]`
 
 **Type**: `list[str]`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.src]
 exclude = [
     "generated",
@@ -399,9 +399,9 @@ matches `<project_root>/src` and not `<project_root>/test/src`).
 
 **Type**: `list[str]`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.src]
 include = [
     "src",
@@ -421,9 +421,9 @@ Enabled by default.
 
 **Type**: `bool`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.src]
 respect-ignore-files = false
 ```
@@ -450,9 +450,9 @@ it will also be included in the first party search path.
 
 **Type**: `str`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.src]
 root = "./app"
 ```
@@ -471,9 +471,9 @@ Defaults to `false`.
 
 **Type**: `bool`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.terminal]
 # Error if ty emits any warning-level diagnostics.
 error-on-warning = true
@@ -491,9 +491,9 @@ Defaults to `full`.
 
 **Type**: `full | concise`
 
-**Example usage** (`pyproject.toml`):
+**Example usage**:
 
-```toml
+```toml title="pyproject.toml"
 [tool.ty.terminal]
 output-format = "concise"
 ```