@scalar/openapi-to-markdown 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @scalar/openapi-to-markdown
 
+## 1.2.0
+
+### Minor Changes
+
+- [#10186](https://github.com/scalar/scalar/pull/10186): Support document-defined additional operations in Markdown operation, webhook, and tag selections. Preserve custom method spelling and inherited parameters, servers, and security when copying an operation as Markdown.
+
+### Patch Changes
+
+- [#10329](https://github.com/scalar/scalar/pull/10329): Render each shared schema once per page. The first reference to a structured schema expands it and labels it with its name (for example `schema: Account`). Later references print "Schema `Account` is shown above." instead of expanding it again. Model sections for schemas already expanded on the page refer back to them too. True cycles still print `[Circular Reference]`. This keeps Markdown output proportional to the schema graph, rather than to the number of paths through it. Before this change, densely linked descriptions such as Stripe's ran out of memory when rendering a single operation.
+
+  A node budget per operation and model section adds a visible `[Schema output truncated]` marker as a last resort. Generated examples that would exceed 10,000 values are omitted with a note. References past the depth limit now point to the model's own section instead of being cut off.
+
+## 1.1.0
+
+### Minor Changes
+
+- [#10251](https://github.com/scalar/scalar/pull/10251): Preserve chained path-item references with non-enumerable links.
+
+  Remove the HTML output APIs `createHtmlFromOpenApi` and `renderer.renderHtml` from `@scalar/openapi-to-markdown`. Use `createMarkdownFromOpenApi` or `renderer.render` and convert the resulting Markdown with an application-provided renderer when HTML is needed.
+
+- [#10222](https://github.com/scalar/scalar/pull/10222): Add a Copy as Markdown button to operations and webhooks in both API Reference layouts. Add a browser entry point for converting resolved OpenAPI documents to Markdown.
+
+### Patch Changes
+
+- [#10275](https://github.com/scalar/scalar/pull/10275): Preserve operation and schema details, supplied and named examples, response headers and links, and request encoding metadata in Markdown output. Render composition siblings and schema annotations, respect readOnly/writeOnly when generating examples, and distinguish recursive references from deep schemas.
+- [#10211](https://github.com/scalar/scalar/pull/10211): Preserve literal data and tag groups when upgrading to OpenAPI 3.2, migrate XML metadata only in schemas, and remove incompatible legacy XML flags. Make 3.2 upgrades leave the input unchanged, match the complete source version, prevent previously inactive parameter settings from changing serialization, and report path-specific errors for detected compatibility issues that require an author's decision.
+
+  Tag `kind` values may change: navigation groups are classified from actual operation-tag usage instead of name substrings. Malformed 3.1 versions now report explicit errors, and successful 3.2 upgrades clone the input only once.
+
+  Expose `UpgradeIncompatibilityError` so Markdown generation can retain OpenAPI 3.1 for descriptions requiring author decisions instead of failing or silently changing semantics. Clone safety and malformed-version errors still propagate.
+
+  The mock server also retains OpenAPI 3.1 when the strict 3.2 migration reports compatibility diagnostics. Existing inline XML descriptions continue loading without inventing element names.
+
+  Read only own data properties during migration so inherited parameter lists, XML metadata, and reference targets cannot modify prototype-owned objects.
+
+  Add `upgrade(input, '3.2', { onIncompatible: 'collect' })` to return a complete document and compatibility diagnostics. Compatible descriptions upgrade to 3.2; incompatible descriptions retain 3.1 without partial transformations. Strict mode remains the default, and malformed-version and clone-safety errors still propagate. The Markdown converter and mock server now use the shared collect mode.
+
 ## 1.0.2
 
 ## 1.0.1

package/README.md

@@ -134,10 +134,8 @@ Schema normalization and description parsing are cached within each renderer. Re
 schema expansion still tracks ancestors and stops at a depth of ten. Output may use tighter
 list spacing and normalized Markdown escaping compared with earlier versions.
 
-### HTML output
-
-`createHtmlFromOpenApi` and `renderer.renderHtml` remain available. They convert the
-Markdown output to HTML on demand, without loading a Vue renderer.
+The package only generates Markdown. To produce HTML, pass the Markdown output to a
+Markdown renderer in your application.
 
 ## Community
 
@@ -178,3 +176,21 @@ Omitting options, or passing `{}`, renders the whole document. OpenAPI 2.0 input
 Invalid, combined, or missing selectors reject the returned promise with an error. Duplicate operation IDs are ambiguous and list matching paths and methods; use a path/method selector instead. Duplicate tag declarations are also rejected. Names are case sensitive. Operation JSON pointers must target `/paths/{path}/{method}`, with an optional leading `#` and standard `~0`/`~1` escaping.
 
 Selection does not add support for every OpenAPI or JSON Schema keyword. Callbacks are not selectable pages. External references follow the existing workspace loader behavior. Recursive schema expansion stops on a repeated ancestor, with a depth limit of ten as a fallback. Shared dependencies have one component section, but may also appear inline where used. Authentication lists alternatives separately; schemes within one requirement must be used together.
+
+### Copying Markdown in the browser
+
+Use the browser entry point with an OpenAPI document already resolved by
+`@scalar/workspace-store`. It supports the same page selectors as the default
+entry point, without file loading or HTML minification.
+
+```ts
+const { createMarkdownFromOpenApi } =
+  await import('@scalar/openapi-to-markdown/browser')
+
+const markdown = await createMarkdownFromOpenApi(document, {
+  operation: { path: '/users/{id}', method: 'get' },
+})
+```
+
+Use the default entry point for raw JSON, YAML, URLs, or file paths that still need
+loading, migration, and reference resolution.

package/dist/browser.d.ts

@@ -0,0 +1,9 @@
+import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { type OpenApiRenderOptions } from './select-document.js';
+/**
+ * Convert an OpenAPI document from the workspace store to Markdown in the browser.
+ * References must already be resolved by the store. This entry point does not load
+ * files, fetch URLs, or migrate raw API descriptions.
+ */
+export declare const createMarkdownFromOpenApi: (document: OpenApiDocument, options?: OpenApiRenderOptions) => Promise<string>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAGnG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,eAAe,EACzB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAAsE,CAAA"}

package/dist/browser.js

@@ -0,0 +1,8 @@
+import { createDocumentRenderer } from './render-document.js';
+import { selectDocument } from './select-document.js';
+/**
+ * Convert an OpenAPI document from the workspace store to Markdown in the browser.
+ * References must already be resolved by the store. This entry point does not load
+ * files, fetch URLs, or migrate raw API descriptions.
+ */
+export const createMarkdownFromOpenApi = async (document, options) => await createDocumentRenderer()(selectDocument(document, options));

package/dist/create-markdown-from-openapi.d.ts

@@ -4,7 +4,6 @@ type AnyDocument = OpenApiDocument | Record<string, unknown> | string;
 /** A resolved API description that can render multiple pages without loading it again. */
 export type OpenApiMarkdownRenderer = {
     render: (options?: OpenApiRenderOptions) => Promise<string>;
-    renderHtml: (options?: OpenApiRenderOptions) => Promise<string>;
 };
 /**
  * Load and resolve an API description once, then render any number of selections.
@@ -13,7 +12,5 @@ export type OpenApiMarkdownRenderer = {
 export declare const createOpenApiMarkdownRenderer: (input: AnyDocument) => Promise<OpenApiMarkdownRenderer>;
 /** Generate Markdown from an API description, optionally scoped to a single page. */
 export declare const createMarkdownFromOpenApi: (input: AnyDocument, options?: OpenApiRenderOptions) => Promise<string>;
-/** Generate HTML through the optional Markdown conversion path. */
-export declare const createHtmlFromOpenApi: (input: AnyDocument, options?: OpenApiRenderOptions) => Promise<string>;
 export {};
 //# sourceMappingURL=create-markdown-from-openapi.d.ts.map

package/dist/create-markdown-from-openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAInG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3D,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAChE,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GAAU,OAAO,WAAW,KAAG,OAAO,CAAC,uBAAuB,CAoBvG,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAGhB,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,GAAU,OAAO,WAAW,EAAE,UAAU,oBAAoB,KAAG,OAAO,CAAC,MAAM,CAG9G,CAAA"}
+{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAInG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GAAU,OAAO,WAAW,KAAG,OAAO,CAAC,uBAAuB,CAOvG,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAGhB,CAAA"}

package/dist/create-markdown-from-openapi.js

@@ -9,27 +9,10 @@ export const createOpenApiMarkdownRenderer = async (input) => {
     const content = await loadDocument(input);
     const renderDocument = createDocumentRenderer();
     const render = async (options) => await renderDocument(selectDocument(content, options));
-    return {
-        render,
-        renderHtml: async (options) => {
-            const [{ unified }, { default: remarkParse }, { default: remarkRehype }, { default: rehypeStringify }] = await Promise.all([
-                import('unified'),
-                import('remark-parse'),
-                import('remark-rehype'),
-                import('rehype-stringify'),
-            ]);
-            const processor = unified().use(remarkParse).use(remarkRehype).use(rehypeStringify);
-            return processor.processSync(await render(options)).toString();
-        },
-    };
+    return { render };
 };
 /** Generate Markdown from an API description, optionally scoped to a single page. */
 export const createMarkdownFromOpenApi = async (input, options) => {
     const renderer = await createOpenApiMarkdownRenderer(input);
     return renderer.render(options);
 };
-/** Generate HTML through the optional Markdown conversion path. */
-export const createHtmlFromOpenApi = async (input, options) => {
-    const renderer = await createOpenApiMarkdownRenderer(input);
-    return renderer.renderHtml(options);
-};

package/dist/get-markdown-examples.d.ts

@@ -0,0 +1,29 @@
+/** Example-bearing media types, parameters, and headers share the same precedence rules. */
+export type ExampleSource = {
+    schema?: unknown;
+    example?: unknown;
+    examples?: Record<string, unknown>;
+};
+/** Named examples can contain a literal value or point to an external value. */
+type MarkdownExample = {
+    name?: string;
+    summary?: string;
+    description?: string;
+} & ({
+    value: unknown;
+} | {
+    externalValue: string;
+} | {
+    serializedValue: string;
+} | {
+    omitted: true;
+});
+/**
+ * Estimate how many values an example generated from this schema contains, stopping just past the limit.
+ * Counts are cached per schema and level, so this is linear in the size of the schema graph.
+ */
+export declare const countGeneratedExampleValues: (root: unknown, limit?: number) => number;
+/** Preserve supplied values; generate a fallback only when examples are not supplied. */
+export declare const getMarkdownExamples: (source: ExampleSource, mediaType: string, mode?: "read" | "write", openapiVersion?: string) => MarkdownExample[];
+export {};
+//# sourceMappingURL=get-markdown-examples.d.ts.map

package/dist/get-markdown-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAKA,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,gFAAgF;AAChF,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAYtG;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,OAAO,EAAE,cAAoC,KAAG,MA2CjG,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,aAAa,EACrB,WAAW,MAAM,EACjB,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,KACvB,eAAe,EA4BjB,CAAA"}

package/dist/get-markdown-examples.js

@@ -0,0 +1,105 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
+/** Mirrors the depth at which `getExampleFromSchema` stops following nested schemas. */
+const EXAMPLE_DEPTH = 10;
+/**
+ * Generated examples repeat every shared schema at each place it is used, up to ten levels deep.
+ * A densely shared schema graph therefore produces billions of values, so larger examples are skipped.
+ * The largest generated examples in the Stripe, GitHub, and Cloudflare descriptions have about 7,600 values.
+ */
+const MAX_GENERATED_EXAMPLE_VALUES = 10_000;
+/**
+ * Estimate how many values an example generated from this schema contains, stopping just past the limit.
+ * Counts are cached per schema and level, so this is linear in the size of the schema graph.
+ */
+export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_VALUES) => {
+    const counts = new WeakMap();
+    const count = (input, level) => {
+        if (level > EXAMPLE_DEPTH || !isObject(input))
+            return 1;
+        const cached = counts.get(input)?.get(level);
+        if (cached !== undefined)
+            return cached;
+        const schema = getResolvedRef(input, mergeSiblingReferences);
+        if (!isObject(schema))
+            return 1;
+        // Supplied examples bypass schema expansion in the generator too.
+        if (schema.example !== undefined || (Array.isArray(schema.examples) && schema.examples.length > 0))
+            return 1;
+        let total = 1;
+        const add = (child) => {
+            if (total <= limit)
+                total += count(child, level + 1);
+        };
+        if (isObject(schema.properties))
+            Object.values(schema.properties).forEach(add);
+        if (isObject(schema.patternProperties))
+            Object.values(schema.patternProperties).forEach(add);
+        if (isObject(schema.additionalProperties))
+            add(schema.additionalProperties);
+        if (schema.items !== undefined)
+            add(schema.items);
+        if (Array.isArray(schema.prefixItems))
+            schema.prefixItems.forEach(add);
+        if (Array.isArray(schema.allOf))
+            schema.allOf.forEach(add);
+        const variants = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : [];
+        // Object and array generation can use the first variant, while other unions skip null.
+        // A discriminator can choose any variant, so bound the largest candidate in that case.
+        const nonNull = variants.find((variant) => {
+            const resolved = getResolvedRef(variant, mergeSiblingReferences);
+            return isObject(resolved) && resolved.type !== 'null';
+        });
+        const candidates = isObject(schema.discriminator) && schema.discriminator.defaultMapping !== undefined
+            ? variants
+            : [variants[0], nonNull];
+        let variantCount = 0;
+        for (const candidate of candidates) {
+            if (candidate !== undefined && total <= limit && variantCount <= limit)
+                variantCount = Math.max(variantCount, count(candidate, level + 1));
+        }
+        total += variantCount;
+        const levels = counts.get(input) ?? new Map();
+        levels.set(level, total);
+        counts.set(input, levels);
+        return total;
+    };
+    return count(root, 0);
+};
+/** Preserve supplied values; generate a fallback only when examples are not supplied. */
+export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3.2.0') => {
+    if (source.example !== undefined)
+        return [{ value: source.example }];
+    if (source.examples && Object.keys(source.examples).length) {
+        return Object.entries(source.examples).flatMap(([name, reference]) => {
+            const example = getResolvedRef(reference);
+            if (!isObject(example))
+                return [];
+            const metadata = {
+                name,
+                summary: typeof example.summary === 'string' ? example.summary : undefined,
+                description: typeof example.description === 'string' ? example.description : undefined,
+            };
+            if (example.value !== undefined)
+                return [{ ...metadata, value: example.value }];
+            if (/^3\.2\./.test(openapiVersion) && typeof example.serializedValue === 'string')
+                return [{ ...metadata, serializedValue: example.serializedValue }];
+            if (typeof example.externalValue === 'string')
+                return [{ ...metadata, externalValue: example.externalValue }];
+            if (/^3\.2\./.test(openapiVersion) && example.dataValue !== undefined)
+                return [{ ...metadata, value: example.dataValue }];
+            return [];
+        });
+    }
+    const schema = getResolvedRef(source.schema);
+    if (!isObject(schema))
+        return [];
+    if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES)
+        return [{ omitted: true }];
+    const value = getExampleFromSchema(getResolvedRef(source.schema, mergeSiblingReferences), {
+        xml: mediaType.includes('xml'),
+        mode,
+    });
+    return value === undefined ? [] : [{ value }];
+};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { HttpMethod } from '@scalar/helpers/http/http-methods';
 export type { OpenApiMarkdownRenderer } from './create-markdown-from-openapi.js';
-export { createHtmlFromOpenApi, createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';
+export { createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';
 export type { OpenApiRenderOptions, OperationSelector } from './select-document.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAEnE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,EACL,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -1 +1 @@
-export { createHtmlFromOpenApi, createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';
+export { createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';

package/dist/load-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-document.d.ts","sourceRoot":"","sources":["../src/load-document.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,8DAA8D,CAAA;AAyErE,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,KACxD,OAAO,CAAC,eAAe,CAoFzB,CAAA"}
+{"version":3,"file":"load-document.d.ts","sourceRoot":"","sources":["../src/load-document.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,8DAA8D,CAAA;AA2ErE,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,KACxD,OAAO,CAAC,eAAe,CA0FzB,CAAA"}

package/dist/load-document.js

@@ -10,6 +10,7 @@ import { upgrade } from '@scalar/openapi-upgrader';
 import { deepClone } from '@scalar/workspace-store/helpers/deep-clone';
 import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
 import { OpenAPIDocumentSchema, } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { restoreBooleanSchemas } from './restore-boolean-schemas.js';
 /**
  * Link references in a private, bundled document without proxies or expanded copies.
  * JSON Magic owns `$id` and anchor indexing, which keeps local-reference behavior
@@ -104,7 +105,8 @@ export const loadDocument = async (input) => {
         throw new Error('Failed to load OpenAPI document');
     }
     // Upgrade before indexing so reference resolution sees one consistent dialect.
-    const upgraded = upgrade(raw, '3.2');
+    const declaredOpenapiVersion = typeof raw.openapi === 'string' ? raw.openapi : '2.0';
+    const { document: upgraded } = upgrade(raw, '3.2', { onIncompatible: 'collect' });
     const upgradedSchemas = getSchemas(upgraded);
     const hasExternalReferences = attachRefValues(upgraded, false, upgradedSchemas);
     let document = upgraded;
@@ -134,6 +136,11 @@ export const loadDocument = async (input) => {
     // Restore non-enumerable shared links afterward so rendering never expands the graph.
     attachRefValues(document, true, schemas);
     const coerced = coerceValue(OpenAPIDocumentSchema, document);
+    // Rendering must use the declared version for features added after OpenAPI 3.1.
+    coerced['x-original-oas-version'] = declaredOpenapiVersion;
+    // Boolean schemas were introduced in OpenAPI 3.1; older descriptions retain their existing coercion.
+    if (/^3\.[12]\./.test(declaredOpenapiVersion))
+        restoreBooleanSchemas(document, coerced);
     // Keep extension resources that local and bundled references can target.
     for (const [key, value] of Object.entries(document)) {
         if (key.startsWith('x-') && !(key in coerced)) {

package/dist/render-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,8DAA8D,CAAA;AAcpH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAgIxF,CAAA"}
+{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,8DAA8D,CAAA;AAepH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CA6IxF,CAAA"}

package/dist/render-document.js

@@ -5,6 +5,7 @@ import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
 import { field, heading, inlineCode, item, link, list, paragraph, strong, text } from './markdown-nodes.js';
 import { createDescriptionParser } from './parse-description.js';
+import { renderExamples } from './render-examples.js';
 import { renderOperation } from './render-operation.js';
 import { createSchemaRenderer } from './render-schema.js';
 import { renderSecurity } from './render-security.js';
@@ -12,9 +13,11 @@ const serializer = unified().use(remarkGfm).use(remarkStringify, { bullet: '-' }
 /** Build Markdown directly, retaining caches only for this immutable document snapshot. */
 export const createDocumentRenderer = () => {
     const descriptions = createDescriptionParser();
-    const schemas = createSchemaRenderer();
+    const schemaRenderer = createSchemaRenderer();
     return async (document) => {
         const description = descriptions();
+        // Each page expands a shared schema once, then refers back to it.
+        const schemas = schemaRenderer.forDocument(document.components?.schemas);
         const { info } = document;
         const metadata = [
             field('OpenAPI Version', inlineCode(document.openapi)),
@@ -84,6 +87,7 @@ export const createDocumentRenderer = () => {
                         nodes.push(heading(2, text(group.title)));
                         hasOperations = true;
                     }
+                    schemas.beginSection();
                     nodes.push(...(await renderOperation(document, path, method, pathItem, operation, group.webhook, {
                         description,
                         schemas,
@@ -96,14 +100,15 @@ export const createDocumentRenderer = () => {
         if (models.length)
             nodes.push(heading(2, text('Schemas')));
         for (const [name, schema] of models) {
+            schemas.beginSection();
             const view = schemas.view(schema);
             nodes.push(heading(3, text(view.title ?? name)), list([
                 view.type
                     ? field('Type', inlineCode(Array.isArray(view.type) ? view.type.join(' | ') : view.type))
                     : item(paragraph(strong(text('Type:')))),
-            ]), ...(await description(view.description)), ...schemas.render(schema));
+            ]), ...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDescription: true, name }));
             if (view.type === 'object')
-                nodes.push(paragraph(strong(text('Example:'))), schemas.example(schema));
+                nodes.push(...(await renderExamples({ schema }, description, 'application/json', undefined, document['x-original-oas-version'] ?? document.openapi)));
             flush();
         }
         flush();

package/dist/render-examples.d.ts

@@ -0,0 +1,6 @@
+import type { RootContent } from 'mdast';
+import { type ExampleSource } from './get-markdown-examples.js';
+import type { DescriptionParser } from './parse-description.js';
+/** Render supplied examples before considering a schema-generated fallback. */
+export declare const renderExamples: (source: ExampleSource, description: DescriptionParser, mediaType?: string, mode?: "read" | "write", openapiVersion?: string) => Promise<RootContent[]>;
+//# sourceMappingURL=render-examples.d.ts.map

package/dist/render-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAExC,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,KACvB,OAAO,CAAC,WAAW,EAAE,CAqCvB,CAAA"}

package/dist/render-examples.js

@@ -0,0 +1,41 @@
+import { json2xml } from '@scalar/helpers/file/json2xml';
+import { getMarkdownExamples } from './get-markdown-examples.js';
+import { link, paragraph, strong, text } from './markdown-nodes.js';
+/** Render supplied examples before considering a schema-generated fallback. */
+export const renderExamples = async (source, description, mediaType = 'application/json', mode, openapiVersion = '3.2.0') => {
+    const nodes = [];
+    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion)) {
+        nodes.push(paragraph(strong(text(example.name ? `Example: ${example.name}` : 'Example:'))));
+        if ('omitted' in example) {
+            nodes.push(paragraph(text('[Generated example omitted because it is too large]')));
+            continue;
+        }
+        if (example.summary)
+            nodes.push(paragraph(text(example.summary)));
+        nodes.push(...(await description(example.description)));
+        if ('externalValue' in example) {
+            nodes.push(paragraph(strong(text('External value:')), text(' '), link(example.externalValue, example.externalValue)));
+            continue;
+        }
+        if ('serializedValue' in example) {
+            nodes.push({
+                type: 'code',
+                lang: mediaType.includes('xml') ? 'xml' : mediaType.includes('json') ? 'json' : 'text',
+                value: example.serializedValue,
+            });
+            continue;
+        }
+        const xml = mediaType.includes('xml');
+        nodes.push({
+            type: 'code',
+            lang: xml ? 'xml' : 'json',
+            // XML strings are already serialized; primitives must not become object keys.
+            value: xml
+                ? example.value !== null && typeof example.value === 'object'
+                    ? json2xml(example.value)
+                    : String(example.value)
+                : (JSON.stringify(example.value, null, 2) ?? ''),
+        });
+    }
+    return nodes;
+};

package/dist/render-operation-details.d.ts

@@ -0,0 +1,11 @@
+import type { EncodingObject, ResponseObject } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import type { RootContent } from 'mdast';
+import type { DescriptionParser } from './parse-description.js';
+import type { SchemaRenderer } from './render-schema.js';
+/** Render response or multipart headers, whose names come from their containing map. */
+export declare const renderHeaders: (headers: ResponseObject["headers"], description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string) => Promise<RootContent[]>;
+/** Preserve explicit encoding settings, including false flags and part headers. */
+export declare const renderEncoding: (encoding: Record<string, EncodingObject> | undefined, mediaType: string, description: DescriptionParser, schemas: SchemaRenderer, openapiVersion: string) => Promise<RootContent[]>;
+/** Render response link expressions as literal values, without evaluating them. */
+export declare const renderResponseLinks: (links: ResponseObject["links"], description: DescriptionParser) => Promise<RootContent[]>;
+//# sourceMappingURL=render-operation-details.d.ts.map

package/dist/render-operation-details.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-operation-details.d.ts","sourceRoot":"","sources":["../src/render-operation-details.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAA;AAClH,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,wFAAwF;AACxF,eAAO,MAAM,aAAa,GACxB,SAAS,cAAc,CAAC,SAAS,CAAC,EAClC,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,KACrB,OAAO,CAAC,WAAW,EAAE,CAkCvB,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,EACpD,WAAW,MAAM,EACjB,aAAa,iBAAiB,EAC9B,SAAS,cAAc,EACvB,gBAAgB,MAAM,KACrB,OAAO,CAAC,WAAW,EAAE,CAuBvB,CAAA;AAID,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,cAAc,CAAC,OAAO,CAAC,EAC9B,aAAa,iBAAiB,KAC7B,OAAO,CAAC,WAAW,EAAE,CA2BvB,CAAA"}

package/dist/render-operation-details.js

@@ -0,0 +1,85 @@
+import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
+import { renderExamples } from './render-examples.js';
+/** Render response or multipart headers, whose names come from their containing map. */
+export const renderHeaders = async (headers, description, schemas, openapiVersion) => {
+    const entries = [];
+    for (const [name, reference] of Object.entries(headers ?? {})) {
+        // OpenAPI reserves Content-Type for the media type map / encoding field.
+        if (name.toLowerCase() === 'content-type')
+            continue;
+        if (!getResolvedRef(reference))
+            continue;
+        const header = getResolvedRef(reference, mergeSiblingReferences);
+        const blocks = [
+            paragraph(strong(inlineCode(name)), text(header.required ? ' (required)' : '')),
+            ...(await description(header.description)),
+        ];
+        if ('schema' in header && header.schema !== undefined)
+            blocks.push(...schemas.render(header.schema));
+        if ('example' in header || 'examples' in header) {
+            blocks.push(...(await renderExamples({ example: header.example, examples: header.examples }, description, 'application/json', undefined, openapiVersion)));
+        }
+        for (const [mediaType, content] of Object.entries('content' in header ? (header.content ?? {}) : {})) {
+            blocks.push(paragraph(strong(text('Content-Type:')), text(` ${mediaType}`)));
+            if (content.schema !== undefined)
+                blocks.push(...schemas.render(content.schema));
+            blocks.push(...(await renderExamples(content, description, mediaType, undefined, openapiVersion)));
+        }
+        entries.push(item(...blocks));
+    }
+    return entries.length ? [paragraph(strong(text('Headers:'))), list(entries)] : [];
+};
+/** Preserve explicit encoding settings, including false flags and part headers. */
+export const renderEncoding = async (encoding, mediaType, description, schemas, openapiVersion) => {
+    const multipart = mediaType.startsWith('multipart/');
+    if (!multipart && mediaType !== 'application/x-www-form-urlencoded')
+        return [];
+    const entries = [];
+    for (const [name, entry] of Object.entries(encoding ?? {})) {
+        const fields = [];
+        for (const [key, label] of [
+            ['contentType', 'Content-Type'],
+            ['style', 'Style'],
+            ['explode', 'Explode'],
+            ['allowReserved', 'Allow reserved'],
+        ]) {
+            if (entry[key] !== undefined)
+                fields.push(item(paragraph(text(`${label}: `), inlineCode(entry[key]))));
+        }
+        const blocks = [paragraph(strong(inlineCode(name)))];
+        if (fields.length)
+            blocks.push(list(fields));
+        if (multipart)
+            blocks.push(...(await renderHeaders(entry.headers, description, schemas, openapiVersion)));
+        entries.push(item(...blocks));
+    }
+    return entries.length ? [paragraph(strong(text('Encoding:'))), list(entries)] : [];
+};
+const formatValue = (value) => (typeof value === 'string' ? value : (JSON.stringify(value) ?? ''));
+/** Render response link expressions as literal values, without evaluating them. */
+export const renderResponseLinks = async (links, description) => {
+    const entries = [];
+    for (const [name, reference] of Object.entries(links ?? {})) {
+        if (!getResolvedRef(reference))
+            continue;
+        const link = getResolvedRef(reference, mergeSiblingReferences);
+        const blocks = [
+            paragraph(strong(text(name))),
+            ...(await description(link.description)),
+        ];
+        if (link.operationId)
+            blocks.push(paragraph(strong(text('Operation ID:')), text(' '), inlineCode(link.operationId)));
+        if (link.operationRef)
+            blocks.push(paragraph(strong(text('Operation reference:')), text(' '), inlineCode(link.operationRef)));
+        const parameters = Object.entries(link.parameters ?? {});
+        if (parameters.length)
+            blocks.push(list(parameters.map(([name, value]) => item(paragraph(strong(text(`${name}:`)), text(' '), inlineCode(formatValue(value)))))));
+        if (link.requestBody !== undefined)
+            blocks.push(paragraph(strong(text('Request body:')), text(' '), inlineCode(formatValue(link.requestBody))));
+        if (link.server)
+            blocks.push(paragraph(strong(text('Server:')), text(' '), inlineCode(link.server.url)));
+        entries.push(item(...blocks));
+    }
+    return entries.length ? [paragraph(strong(text('Links:'))), list(entries)] : [];
+};

package/dist/render-operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,0BAA0B,aAAa,KACtC,OAAO,CAAC,WAAW,EAAE,CAgGvB,CAAA"}
+{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,0BAA0B,aAAa,KACtC,OAAO,CAAC,WAAW,EAAE,CAyGvB,CAAA"}