@scalar/openapi-to-markdown 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalar/openapi-to-markdown
 
+## 1.4.0
+
+### Minor Changes
+
+- [#10394](https://github.com/scalar/scalar/pull/10394): Add opt-in linked schema rendering with caller-supplied model URLs for bounded operation, model, and webhook pages. Keep default expansion unchanged, retain reference siblings and inline schemas, and omit generated examples in linked mode.
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -194,3 +194,54 @@ const markdown = await createMarkdownFromOpenApi(document, {
 
 Use the default entry point for raw JSON, YAML, URLs, or file paths that still need
 loading, migration, and reference resolution.
+
+### Link shared schemas on individual pages
+
+The default renderer expands shared schemas and includes the schemas needed by a
+selected page. For large API descriptions, opt into `schemaReferences.mode:
+'linked'` to expand the root schema of each parameter, request, response, or model
+and replace nested `$ref` occurrences with links. Inline schemas continue to
+render, including composition branches and reference siblings. Operation and
+webhook pages do not collect or append transitive models; a model page includes
+only the selected model.
+
+The documentation generator supplies published URLs. The renderer does not assume
+any routing convention:
+
+```ts
+import { createOpenApiMarkdownRenderer } from '@scalar/openapi-to-markdown'
+
+const renderer = await createOpenApiMarkdownRenderer(apiDescription)
+// Build this map from the pages your generator actually publishes.
+const modelUrls = new Map([
+  ['account', '/reference/models/account'],
+  ['customer', '/reference/models/customer'],
+])
+const markdown = await renderer.render({
+  operation: { path: '/v1/account', method: 'get' },
+  schemaReferences: {
+    mode: 'linked',
+    resolveUrl: ({ name }) => modelUrls.get(name),
+  },
+})
+```
+
+The callback receives the original reference string (`ref`) and its decoded
+component name (`name`). For references outside `#/components/schemas/{name}`,
+`name` is the reference string. Returning `undefined`, an empty URL, or an unsafe
+URL retains the schema name as text. Omitting the callback has the same fallback.
+References remain visible even when no destination page exists.
+
+Use the same option with `{ model: 'account' }`, `{ webhook: { name: 'event',
+method: 'post' } }`, the one-shot `createMarkdownFromOpenApi`, or the browser entry
+point. The browser entry point still requires a workspace-resolved document.
+Options and URL callbacks are isolated per render, including concurrent renders.
+
+Linked mode omits schema-generated examples with an explicit note, avoiding
+expansion through the example generator. Authored media-type and schema examples
+remain available. Their size is not capped. Inline schema content and authored
+text also remain proportional to the source; this mode bounds traversal across
+shared references, not the byte size of arbitrary authored content. Root
+composition branches that contain references link to those schemas rather than
+flattening their constraints. Full-document exports still include every model
+section; use a page selector for individual exports.

package/dist/browser.d.ts.map

@@ -1 +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"}
+{"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,CAA+E,CAAA"}

package/dist/browser.js

@@ -5,4 +5,4 @@ import { selectDocument } from './select-document.js';
  * 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));
+export const createMarkdownFromOpenApi = async (document, options) => await createDocumentRenderer()(selectDocument(document, options), options);

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

@@ -8,7 +8,7 @@ import { selectDocument } from './select-document.js';
 export const createOpenApiMarkdownRenderer = async (input) => {
     const content = await loadDocument(input);
     const renderDocument = createDocumentRenderer();
-    const render = async (options) => await renderDocument(selectDocument(content, options));
+    const render = async (options) => await renderDocument(selectDocument(content, options), options);
     return { render };
 };
 /** Generate Markdown from an API description, optionally scoped to a single page. */

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

@@ -28,6 +28,6 @@ type MarkdownExample = {
  */
 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, schemaOpenapiVersion?: string) => MarkdownExample[];
+export declare const getMarkdownExamples: (source: ExampleSource, mediaType: string, mode?: "read" | "write", openapiVersion?: string, schemaOpenapiVersion?: string, linked?: boolean) => MarkdownExample[];
 export {};
 //# sourceMappingURL=get-markdown-examples.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAMA,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,CACA;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAClB;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CACpB,CAAA;AAYD;;;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,EAExB,6BAAqC,KACpC,eAAe,EAoCjB,CAAA"}
+{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAMA,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,CACA;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAClB;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CACpB,CAAA;AAYD;;;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,EAExB,6BAAqC,EACrC,gBAAc,KACb,eAAe,EA2CjB,CAAA"}

package/dist/get-markdown-examples.js

@@ -71,7 +71,7 @@ export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_
 /** Preserve supplied values; generate a fallback only when examples are not supplied. */
 export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3.2.0', 
 // Schema metadata can be upgraded while example fields still follow the original version.
-schemaOpenapiVersion = openapiVersion) => {
+schemaOpenapiVersion = openapiVersion, linked = false) => {
     if (source.example !== undefined)
         return [{ value: source.example }];
     if (source.examples && Object.keys(source.examples).length) {
@@ -95,9 +95,18 @@ schemaOpenapiVersion = openapiVersion) => {
             return [];
         });
     }
-    const schema = getResolvedRef(source.schema);
+    const schema = linked
+        ? getResolvedRef(source.schema, mergeSiblingReferences)
+        : getResolvedRef(source.schema);
     if (!isObject(schema))
         return [];
+    if (linked) {
+        if (schema.example !== undefined)
+            return [{ value: schema.example }];
+        if (Array.isArray(schema.examples) && schema.examples.length)
+            return schema.examples.map((value) => ({ value }));
+        return [{ omitted: true }];
+    }
     if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES)
         return [{ omitted: true }];
     if (isXmlMediaType(mediaType)) {

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 { createMarkdownFromOpenApi, createOpenApiMarkdownRenderer, } from './create-markdown-from-openapi.js';
-export type { OpenApiRenderOptions, OperationSelector } from './select-document.js';
+export type { OpenApiRenderOptions, OperationSelector, SchemaReferenceOptions } 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,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,sBAAsB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/render-document.d.ts

@@ -1,4 +1,5 @@
 import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import type { SchemaReferenceOptions } from './select-document.js';
 /** Build Markdown directly, retaining caches only for this immutable document snapshot. */
-export declare const createDocumentRenderer: () => ((document: OpenApiDocument) => Promise<string>);
+export declare const createDocumentRenderer: () => ((document: OpenApiDocument, options?: SchemaReferenceOptions) => Promise<string>);
 //# sourceMappingURL=render-document.d.ts.map

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;AAepH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CA6IxF,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;AAYpH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAI/D,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,sBAAsB,KAC7B,OAAO,CAAC,MAAM,CAAC,CA+InB,CAAA"}

package/dist/render-document.js

@@ -14,10 +14,10 @@ const serializer = unified().use(remarkGfm).use(remarkStringify, { bullet: '-' }
 export const createDocumentRenderer = () => {
     const descriptions = createDescriptionParser();
     const schemaRenderer = createSchemaRenderer();
-    return async (document) => {
+    return async (document, options) => {
         const description = descriptions();
         // Each page expands a shared schema once, then refers back to it.
-        const schemas = schemaRenderer.forDocument(document.components?.schemas);
+        const schemas = schemaRenderer.forDocument(document.components?.schemas, options);
         const { info } = document;
         const metadata = [
             field('OpenAPI Version', inlineCode(document.openapi)),
@@ -108,7 +108,7 @@ export const createDocumentRenderer = () => {
                     : item(paragraph(strong(text('Type:')))),
             ]), ...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDescription: true, name }));
             if (view.type === 'object')
-                nodes.push(...(await renderExamples({ schema }, description, 'application/json', undefined, document['x-original-oas-version'] ?? document.openapi)));
+                nodes.push(...(await renderExamples({ schema }, description, 'application/json', undefined, document['x-original-oas-version'] ?? document.openapi, document.openapi, schemas.linked)));
             flush();
         }
         flush();

package/dist/render-examples.d.ts

@@ -2,5 +2,5 @@ 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, schemaOpenapiVersion?: string) => Promise<RootContent[]>;
+export declare const renderExamples: (source: ExampleSource, description: DescriptionParser, mediaType?: string, mode?: "read" | "write", openapiVersion?: string, schemaOpenapiVersion?: string, linked?: boolean) => Promise<RootContent[]>;
 //# sourceMappingURL=render-examples.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AAGA,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,EAExB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CAmDvB,CAAA"}
+{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AAGA,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,EAExB,6BAAqC,EACrC,gBAAc,KACb,OAAO,CAAC,WAAW,EAAE,CAyDvB,CAAA"}

package/dist/render-examples.js

@@ -5,12 +5,12 @@ 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', 
 // Schema metadata can be upgraded while example fields still follow the original version.
-schemaOpenapiVersion = openapiVersion) => {
+schemaOpenapiVersion = openapiVersion, linked = false) => {
     const nodes = [];
-    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion, schemaOpenapiVersion)) {
+    for (const example of getMarkdownExamples(source, mediaType, mode, openapiVersion, schemaOpenapiVersion, linked)) {
         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]')));
+            nodes.push(paragraph(text(`${linked ? '[Generated example omitted in linked schema mode; see the schema documentation]' : '[Generated example omitted because it is too large]'}`)));
             continue;
         }
         if (example.summary)

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

@@ -1 +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,EACtB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CA0CvB,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,EACtB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CA6BvB,CAAA;AAID,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,cAAc,CAAC,OAAO,CAAC,EAC9B,aAAa,iBAAiB,KAC7B,OAAO,CAAC,WAAW,EAAE,CA2BvB,CAAA"}
+{"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,EACtB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CA4CvB,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,EACtB,6BAAqC,KACpC,OAAO,CAAC,WAAW,EAAE,CA6BvB,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

@@ -18,13 +18,13 @@ export const renderHeaders = async (headers, description, schemas, openapiVersio
         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, schemaOpenapiVersion)));
+            blocks.push(...(await renderExamples({ example: header.example, examples: header.examples }, description, 'application/json', undefined, openapiVersion, schemaOpenapiVersion, schemas.linked)));
         }
         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, schemaOpenapiVersion)));
+            blocks.push(...(await renderExamples(content, description, mediaType, undefined, openapiVersion, schemaOpenapiVersion, schemas.linked)));
         }
         entries.push(item(...blocks));
     }

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

@@ -1 +1 @@
-{"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,CA4GvB,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,CA0IvB,CAAA"}

package/dist/render-operation.js

@@ -64,7 +64,7 @@ export const renderOperation = async (document, path, method, pathItem, operatio
             nodes.push(heading(6, text(`Content-Type: ${mediaType}`)));
             if (content.schema !== undefined)
                 nodes.push(...schemas.render(content.schema));
-            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion, document.openapi)));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion, document.openapi, schemas.linked)));
         }
     }
     const body = getResolvedRef(operation.requestBody, mergeSiblingReferences);
@@ -76,7 +76,7 @@ export const renderOperation = async (document, path, method, pathItem, operatio
             nodes.push(heading(5, text(`Content-Type: ${mediaType}`)));
             if (content.schema !== undefined)
                 nodes.push(...schemas.render(content.schema));
-            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion, document.openapi)));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'write', openapiVersion, document.openapi, schemas.linked)));
             nodes.push(...(await renderEncoding(content.encoding, mediaType, description, schemas, openapiVersion, document.openapi)));
         }
     }
@@ -93,7 +93,7 @@ export const renderOperation = async (document, path, method, pathItem, operatio
             nodes.push(heading(6, text(`Content-Type: ${mediaType}`)));
             if (content.schema !== undefined)
                 nodes.push(...schemas.render(content.schema));
-            nodes.push(...(await renderExamples(content, description, mediaType, 'read', openapiVersion, document.openapi)));
+            nodes.push(...(await renderExamples(content, description, mediaType, 'read', openapiVersion, document.openapi, schemas.linked)));
         }
     }
     return nodes;

package/dist/render-schema.d.ts

@@ -1,5 +1,6 @@
 import type { MaybeRefSchemaObject, SchemaObject } from '@scalar/workspace-store/schemas/v3.2/strict/schema';
 import type { RootContent } from 'mdast';
+import type { SchemaReferenceOptions } from './select-document.js';
 /** Boolean schemas must survive rendering without being coerced into empty objects. */
 type MarkdownSchema = MaybeRefSchemaObject | boolean;
 type SchemaView = {
@@ -56,12 +57,13 @@ type RenderOptions = {
  * run concurrently, and each needs its own record.
  */
 export type SchemaRenderer = {
+    linked: boolean;
     view: (schema: MarkdownSchema) => SchemaView;
     render: (schema: MarkdownSchema, depth?: number, ancestors?: readonly unknown[], options?: RenderOptions) => RootContent[];
     /** Restore the node budget, for example for each operation or model section. */
     beginSection: () => void;
     /** Start a document that shares normalized views, given the models it renders in its own sections. */
-    forDocument: (models?: Record<string, MarkdownSchema>) => SchemaRenderer;
+    forDocument: (models?: Record<string, MarkdownSchema>, options?: SchemaReferenceOptions) => SchemaRenderer;
 };
 type SchemaRendererOptions = {
     /** Upper bound on expanded schema nodes per section, so no description can make a page unbounded. */

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

@@ -1 +1 @@
-{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"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"}

package/dist/render-schema.js

@@ -1,7 +1,6 @@
-import { unescapeJsonPointer } from '@scalar/helpers/json/unescape-json-pointer';
 import { isObject } from '@scalar/helpers/object/is-object';
 import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
-import { inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
+import { inlineCode, item, link, list, paragraph, safeUrl, strong, text } from './markdown-nodes.js';
 /** Guards against stack exhaustion. Past it, references to models point to their own section instead. */
 const MAX_DEPTH = 64;
 /**
@@ -29,11 +28,10 @@ const referenceKeys = new Set(['$ref', '$ref-value', '$global', '$status']);
 const emphasis = (...children) => ({ type: 'emphasis', children });
 /** Prefer the component name, which is how model sections and other references identify the schema. */
 const getReferenceName = (ref) => {
-    const match = /^#\/components\/schemas\/([^/]+)$/.exec(ref);
-    if (!match)
-        return ref;
     try {
-        return unescapeJsonPointer(match[1]);
+        // URI fragments are decoded before JSON Pointer segments and escapes, exactly once.
+        const match = /^#\/components\/schemas\/([^/]+)$/.exec(decodeURIComponent(ref));
+        return match ? match[1].replaceAll('~1', '/').replaceAll('~0', '~') : ref;
     }
     catch {
         return ref;
@@ -133,7 +131,8 @@ export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
             nodes.push(text(`${nodes.length ? ' — ' : ''}${value.description}`));
         return nodes;
     };
-    const forDocument = (models = {}) => {
+    const forDocument = (models = {}, settings = {}) => {
+        const linked = settings.schemaReferences?.mode === 'linked';
         /** Shared schemas this document already expanded, with the name later references use. */
         const shown = new Map();
         /** Models that the document renders in their own sections after the operations. */
@@ -152,6 +151,31 @@ export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
             return nodes;
         };
         const render = (input, depth = 0, ancestors = [], options = {}) => {
+            if (linked && isObject(input) && '$ref' in input && typeof input.$ref === 'string') {
+                const target = getResolvedRef(input);
+                // Reference siblings are independent constraints, not replacements for target keywords.
+                const siblings = Object.fromEntries(Object.entries(input).filter(([key]) => !referenceKeys.has(key)));
+                const hasSiblings = Object.keys(siblings).length > 0;
+                if (depth > 0 || target === undefined) {
+                    const name = getReferenceName(input.$ref);
+                    const url = settings.schemaReferences?.resolveUrl?.({ ref: input.$ref, name });
+                    const nodes = [
+                        paragraph(text('Schema: '), url && safeUrl(url) ? link(url, name) : inlineCode(name)),
+                    ];
+                    if (hasSiblings)
+                        nodes.push(...render(siblings, depth, ancestors));
+                    return nodes;
+                }
+                // An alias with siblings is another reference boundary. Keep its reference visible
+                // instead of overwriting it with the outer reference during normalization.
+                if (hasSiblings || (isObject(target) && '$ref' in target)) {
+                    return [
+                        ...(hasSiblings ? [paragraph(strong(text('All of:')))] : []),
+                        ...render(target, depth + 1, ancestors),
+                        ...(hasSiblings ? render(siblings, depth, ancestors) : []),
+                    ];
+                }
+            }
             // Follow the original target: merging reference siblings creates fresh objects.
             const identity = getResolvedRef(input) ?? input;
             if (typeof identity === 'object' && ancestors.includes(identity)) {
@@ -206,6 +230,13 @@ export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
                 if (annotations.length)
                     nodes.push(paragraph(...annotations));
             }
+            if (linked) {
+                // A reference sibling may require a field declared only in the target schema.
+                const declared = new Set(value.properties.map(([name]) => name));
+                const required = [...value.required].filter((name) => !declared.has(name));
+                if (required.length)
+                    nodes.push(paragraph(strong(text('Required fields:')), text(' '), inlineCode(required.join(', '))));
+            }
             if (value.properties.length) {
                 const properties = value.properties.map(([name, schema]) => {
                     const child = view(schema);
@@ -244,6 +275,7 @@ export const createSchemaRenderer = ({ maxNodes = MAX_NODES } = {}) => {
             return nodes;
         };
         return {
+            linked,
             view,
             render,
             beginSection: () => {

package/dist/select-document.d.ts

@@ -10,9 +10,21 @@ export type OperationSelector = {
     pointer: string;
 };
 /** Select one reference page, or omit selectors for the whole document. */
-export type OpenApiRenderOptions = {
+export type OpenApiRenderOptions = SchemaReferenceOptions & ({
     [Key in keyof PageSelectors]: Partial<Record<Exclude<keyof PageSelectors, Key>, never>> & Pick<PageSelectors, Key>;
-}[keyof PageSelectors] | Partial<Record<keyof PageSelectors, never>>;
+}[keyof PageSelectors] | Partial<Record<keyof PageSelectors, never>>);
+/** Control shared-schema expansion without assuming a documentation URL layout. */
+export type SchemaReferenceOptions = {
+    /** Expand root schemas, link nested references, and omit generated examples and the transitive appendix. */
+    schemaReferences?: {
+        mode: 'linked';
+        /** Return a published URL, or undefined to retain the schema name as plain text. */
+        resolveUrl?: (reference: {
+            ref: string;
+            name: string;
+        }) => string | undefined;
+    };
+};
 type PageSelectors = {
     operation: OperationSelector;
     tag: string;

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

@@ -1 +1 @@
-{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAC5B;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CACnH,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAAA;AAE/C,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAyKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eAuN9F,CAAA"}
+{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GACvD,CACI;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GACrF,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CAC3B,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAC9C,CAAA;AAEH,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG;IACnC,4GAA4G;IAC5G,gBAAgB,CAAC,EAAE;QACjB,IAAI,EAAE,QAAQ,CAAA;QACd,oFAAoF;QACpF,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,MAAM,GAAG,SAAS,CAAA;KAC9E,CAAA;CACF,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAyKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eA2N9F,CAAA"}

package/dist/select-document.js

@@ -126,7 +126,7 @@ export const selectDocument = (document, options = {}) => {
     if (!isObject(options)) {
         throw new Error('Render options must be an object');
     }
-    const keys = Object.keys(options).filter((key) => options[key] !== undefined);
+    const keys = Object.keys(options).filter((key) => key !== 'schemaReferences' && options[key] !== undefined);
     if (!keys.length) {
         return document;
     }
@@ -320,9 +320,11 @@ export const selectDocument = (document, options = {}) => {
             }
         }
     };
-    visit({ paths: selected.paths, webhooks: selected.webhooks });
-    for (const root of modelRoots) {
-        visit(root);
+    if (options.schemaReferences?.mode !== 'linked') {
+        visit({ paths: selected.paths, webhooks: selected.webhooks });
+        for (const root of modelRoots) {
+            visit(root);
+        }
     }
     selected.components = {
         ...document.components,

package/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.3.0",
+  "version": "1.4.0",
   "engines": {
     "node": ">=22"
   },
@@ -41,10 +41,10 @@
   ],
   "dependencies": {
     "@scalar/code-highlight": "0.4.7",
-    "@scalar/helpers": "0.15.0",
-    "@scalar/json-magic": "0.15.2",
-    "@scalar/openapi-upgrader": "0.4.0",
-    "@scalar/workspace-store": "0.67.0",
+    "@scalar/helpers": "0.16.0",
+    "@scalar/json-magic": "0.15.3",
+    "@scalar/openapi-upgrader": "0.4.1",
+    "@scalar/workspace-store": "0.67.1",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",