fix(wrangler): emit markdownDescription in config schema (#13735)

Author: edmundhung

.changeset/fuzzy-zoos-hear.md

@@ -0,0 +1,7 @@
+---
+"wrangler": patch
+---
+
+Improve `config-schema.json` hover text in more editors
+
+Wrangler now emits `markdownDescription` in `config-schema.json` alongside the existing `description` field. Editors that support rich JSON Schema hovers can use that markdown directly instead of rendering escaped links and formatting.

packages/wrangler/scripts/generate-json-schema.ts

@@ -8,6 +8,7 @@ const config: Config = {
 	tsconfig: join(__dirname, "../../workers-utils/tsconfig.json"),
 	type: "RawConfig",
 	skipTypeCheck: true,
+	markdownDescription: true,
 };
 
 const applyFormattingRules = (schema: Schema) => {

packages/wrangler/src/__tests__/containers/schema.test.ts

@@ -2,20 +2,46 @@ import fs from "node:fs";
 import path from "node:path";
 import { describe, it } from "vitest";
 
-describe("containers config schema", () => {
-	it("documents ssh without exposing wrangler_ssh", ({ expect }) => {
-		const schemaFile = path.join(__dirname, "../../../config-schema.json");
-		const schema = JSON.parse(fs.readFileSync(schemaFile, "utf-8")) as {
-			definitions: {
-				ContainerApp: {
-					properties: Record<string, unknown>;
+type WranglerSchema = {
+	definitions: {
+		ContainerApp: {
+			properties: Record<string, unknown>;
+		};
+		RawConfig: {
+			properties: {
+				build: {
+					description: string;
+					markdownDescription?: string;
 				};
 			};
 		};
+	};
+};
+
+function readSchema(): WranglerSchema {
+	const schemaFile = path.join(__dirname, "../../../config-schema.json");
+	return JSON.parse(fs.readFileSync(schemaFile, "utf-8")) as WranglerSchema;
+}
+
+describe("config schema", () => {
+	it("documents ssh without exposing wrangler_ssh", ({ expect }) => {
+		const schema = readSchema();
 
 		expect(schema.definitions.ContainerApp.properties).toHaveProperty("ssh");
 		expect(schema.definitions.ContainerApp.properties).not.toHaveProperty(
 			"wrangler_ssh"
 		);
 	});
+
+	it("emits markdownDescription for rich editor hovers", ({ expect }) => {
+		const schema = readSchema();
+		const build = schema.definitions.RawConfig.properties.build;
+
+		expect(build.description).toContain(
+			"[custom builds documentation](https://developers.cloudflare.com/workers/cli-wrangler/configuration#build)"
+		);
+		expect(build.markdownDescription).toContain(
+			"[custom builds documentation](https://developers.cloudflare.com/workers/cli-wrangler/configuration#build)"
+		);
+	});
 });