@scalar/openapi-to-markdown 1.5.3 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @scalar/openapi-to-markdown
 
+## 1.6.0
+
+### Minor Changes
+
+- [#10586](https://github.com/scalar/scalar/pull/10586): Add AsyncAPI Markdown conversion with reusable renderers and individual reference pages. Share Markdown description parsing between the OpenAPI and AsyncAPI converters.
+
+  Include shared model links, contents navigation, tag pages, generated examples, and an interactive playground.
+
+  Preserve discriminators and linked schema descriptions, generate examples from primitive aliases, and compact property annotations.
+
+  Include full-export tag documentation, preserve XML schema examples, and normalize annotated primitive aliases.
+
+  Infer enum and const type labels and honor primitive-link settings in generated model examples.
+
+  Preserve AsyncAPI application and schema metadata, explain security alternatives, and render reply and unknown-address semantics accurately.
+
+### Patch Changes
+
+- [#10606](https://github.com/scalar/scalar/pull/10606): Block private-network document requests by default and require an explicit basePath for local files. Apply the same permissions to external references, with an opt-in for trusted private-network inputs.
+- [#10598](https://github.com/scalar/scalar/pull/10598): Preserve OpenAPI 3.2 tag ancestry in Markdown exports with parent-first breadcrumb headings.
+- [#10614](https://github.com/scalar/scalar/pull/10614): Clean up lint warnings while preserving runtime behavior, and document intentional schema and type syntax.
+
+## 1.5.4
+
+### Patch Changes
+
+- [#10559](https://github.com/scalar/scalar/pull/10559): Clean up Biome warnings in package code and tests. Handle rejected debounced callbacks and await streaming writes.
+- [#10505](https://github.com/scalar/scalar/pull/10505): Apply formatting and lint compatibility changes for Biome 2.5.15.
+
 ## 1.5.3
 
 ### Patch Changes

package/README.md

@@ -68,6 +68,27 @@ const operationMarkdownByPointer = await createMarkdownFromOpenApi(content, {
 })
 ```
 
+### Document loading permissions
+
+URL inputs and external references block private, loopback, and link-local addresses by default.
+Protected requests also reject redirects. File access is disabled unless you provide an approved
+`basePath`; paths and symlinks outside that directory are rejected.
+
+```ts
+const markdown = await createMarkdownFromOpenApi('./descriptions/openapi.yaml', {
+  documentLoading: { basePath: './descriptions' },
+})
+
+const renderer = await createOpenApiMarkdownRenderer('./descriptions/openapi.yaml', {
+  basePath: './descriptions',
+})
+```
+
+For trusted local development inputs, set `allowPrivateNetworks: true` in the same loading options.
+This also permits redirects. Keep these permissions under application control, rather than taking
+them from uploaded API descriptions or request parameters. An approved directory applies to all
+files loaded during that call, including references in remote documents.
+
 ### Render multiple pages
 
 Create a reusable renderer when exporting several pages from the same API description.
@@ -144,7 +165,12 @@ schema expansion still tracks ancestors and stops at a depth of ten. Output may
 list spacing and normalized Markdown escaping compared with earlier versions.
 
 For OpenAPI 3.2 descriptions, tag headings use `summary` when present and otherwise
-use `name`. Tag selectors and operation tag metadata continue to use `name`.
+use `name`. Nested tags appear parent-first with breadcrumb headings such as
+`### Accounts › Billing › Invoices`. Every tag uses the same heading level, including
+deeply nested tags. Parent relationships use tag names, while breadcrumb labels use
+summaries when available. Missing parents and circular relationships fall back to flat
+headings. Tag selectors and operation tag metadata continue to use `name`; selecting
+one tag still exports only that tag and its directly tagged operations.
 
 The package only generates Markdown. To produce HTML, pass the Markdown output to a
 Markdown renderer in your application.

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

@@ -1,4 +1,5 @@
 import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { type DocumentLoadOptions } from './load-document.js';
 import { type OpenApiRenderOptions } from './select-document.js';
 type AnyDocument = OpenApiDocument | Record<string, unknown> | string;
 /** A resolved API description that can render multiple pages without loading it again. */
@@ -9,8 +10,10 @@ export type OpenApiMarkdownRenderer = {
  * Load and resolve an API description once, then render any number of selections.
  * Each renderer owns its document; create a new renderer to pick up source changes.
  */
-export declare const createOpenApiMarkdownRenderer: (input: AnyDocument) => Promise<OpenApiMarkdownRenderer>;
+export declare const createOpenApiMarkdownRenderer: (input: AnyDocument, options?: DocumentLoadOptions) => Promise<OpenApiMarkdownRenderer>;
 /** Generate Markdown from an API description, optionally scoped to a single page. */
-export declare const createMarkdownFromOpenApi: (input: AnyDocument, options?: OpenApiRenderOptions) => Promise<string>;
+export declare const createMarkdownFromOpenApi: (input: AnyDocument, options?: OpenApiRenderOptions & {
+    documentLoading?: DocumentLoadOptions;
+}) => 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,EAAwC,MAAM,mBAAmB,CAAA;AAEnG,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,CAQvG,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAGhB,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;AAEnG,OAAO,EAAE,KAAK,mBAAmB,EAAgB,MAAM,iBAAiB,CAAA;AAExE,OAAO,EAAE,KAAK,oBAAoB,EAAwC,MAAM,mBAAmB,CAAA;AAEnG,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,GACxC,OAAO,WAAW,EAClB,UAAU,mBAAmB,KAC5B,OAAO,CAAC,uBAAuB,CAQjC,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,GAAG;IAAE,eAAe,CAAC,EAAE,mBAAmB,CAAA;CAAE,KACzE,OAAO,CAAC,MAAM,CAOhB,CAAA"}

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

@@ -5,8 +5,8 @@ import { createDocumentLookup, selectDocument } from './select-document.js';
  * Load and resolve an API description once, then render any number of selections.
  * Each renderer owns its document; create a new renderer to pick up source changes.
  */
-export const createOpenApiMarkdownRenderer = async (input) => {
-    const content = await loadDocument(input);
+export const createOpenApiMarkdownRenderer = async (input, options) => {
+    const content = await loadDocument(input, options);
     const renderDocument = createDocumentRenderer();
     const lookup = createDocumentLookup(content);
     const render = async (options) => await renderDocument(selectDocument(content, options, lookup), options);
@@ -14,6 +14,10 @@ export const createOpenApiMarkdownRenderer = async (input) => {
 };
 /** Generate Markdown from an API description, optionally scoped to a single page. */
 export const createMarkdownFromOpenApi = async (input, options) => {
-    const renderer = await createOpenApiMarkdownRenderer(input);
+    const renderer = await createOpenApiMarkdownRenderer(input, options?.documentLoading);
+    if (options && 'documentLoading' in options) {
+        const { documentLoading: _, ...renderOptions } = options;
+        return renderer.render(renderOptions);
+    }
     return renderer.render(options);
 };

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

@@ -1 +1 @@
-{"version":3,"file":"document-anchors.d.ts","sourceRoot":"","sources":["../src/document-anchors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEjC,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,QAAO;IACvC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAmBhE,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,MAAM,GAAI,IAAI,MAAM,KAAG,IAAuD,CAAA"}
+{"version":3,"file":"document-anchors.d.ts","sourceRoot":"","sources":["../src/document-anchors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEjC,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,QAAO;IACvC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAuBhE,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,MAAM,GAAI,IAAI,MAAM,KAAG,IAAuD,CAAA"}

package/dist/document-anchors.js

@@ -8,13 +8,15 @@ export const createDocumentAnchors = () => {
         get: (kind, identity, label = identity) => {
             const key = JSON.stringify([kind, identity]);
             const previous = ids.get(key);
-            if (previous !== undefined)
+            if (previous !== undefined) {
                 return previous;
+            }
             const base = `scalar-${kind}-${label}`;
             let id = slugs.slug(base);
             // A literal suffix in a later name can collide with the slugger's numeric suffix.
-            while (used.has(id))
+            while (used.has(id)) {
                 id = slugs.slug(base);
+            }
             used.add(id);
             ids.set(key, id);
             return id;

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

@@ -1 +1 @@
-{"version":3,"file":"document-examples.d.ts","sourceRoot":"","sources":["../src/document-examples.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC/D,OAAO,EAAE,KAAK,aAAa,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAEjF,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,OAAO,mBAAmB,CAAA;IAC/B,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;CAC9F,CAAA;AAaD,uGAAuG;AACvG,eAAO,MAAM,sBAAsB,GAAI,SAAS,UAAU,CAAC,OAAO,qBAAqB,CAAC,KAAG,gBAqC1F,CAAA"}
+{"version":3,"file":"document-examples.d.ts","sourceRoot":"","sources":["../src/document-examples.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC/D,OAAO,EAAE,KAAK,aAAa,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAEjF,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,OAAO,mBAAmB,CAAA;IAC/B,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;CAC9F,CAAA;AAeD,uGAAuG;AACvG,eAAO,MAAM,sBAAsB,GAAI,SAAS,UAAU,CAAC,OAAO,qBAAqB,CAAC,KAAG,gBA4C1F,CAAA"}

package/dist/document-examples.js

@@ -4,8 +4,9 @@ import { getMarkdownExamples } from './get-markdown-examples.js';
 const bookkeeping = new Set(['$ref', '$ref-value', '$global', '$status', '__scalar_']);
 /** Sibling constraints make a reference a different example source from its target. */
 const identity = (source) => {
-    if (!isObject(source.schema))
+    if (!isObject(source.schema)) {
         return undefined;
+    }
     const schema = source.schema;
     const target = '$ref' in schema && Object.keys(schema).every((key) => bookkeeping.has(key)) ? getResolvedRef(schema) : schema;
     return isObject(target) ? target : schema;
@@ -20,12 +21,14 @@ export const createDocumentExamples = (anchors) => {
         get: (...args) => {
             const [source, ...settings] = args;
             const schema = identity(source);
-            if (!schema || source.example !== undefined || Object.keys(source.examples ?? {}).length)
+            if (!schema || source.example !== undefined || Object.keys(source.examples ?? {}).length) {
                 return getMarkdownExamples(...args);
+            }
             const scope = JSON.stringify(settings);
             const previous = cache.get(schema)?.get(scope);
-            if (previous)
+            if (previous) {
                 return previous;
+            }
             // Large APIs must not retain every generated object until the export finishes.
             if (cachedCount >= 256) {
                 cache.clear();
@@ -42,12 +45,14 @@ export const createDocumentExamples = (anchors) => {
             const schema = identity(source);
             const entries = schema ? (shown.get(schema) ?? new Map()) : new Map();
             const previous = entries.get(scope);
-            if (previous?.value === code.value)
+            if (previous?.value === code.value) {
                 return { id: previous.id, previous: true };
+            }
             const id = anchors.get('example', String(++nextId));
             entries.set(scope, { id, value: code.value });
-            if (schema)
+            if (schema) {
                 shown.set(schema, entries);
+            }
             return { id, previous: false };
         },
     };

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;IACpB,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,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,EAyCjB,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;IACpB,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,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,MAmEjG,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,EA6DjB,CAAA"}

package/dist/get-markdown-examples.js

@@ -17,35 +17,47 @@ const MAX_GENERATED_EXAMPLE_VALUES = 10_000;
 export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_VALUES) => {
     const counts = new WeakMap();
     const count = (input, level) => {
-        if (level > EXAMPLE_DEPTH || !isObject(input))
+        if (level > EXAMPLE_DEPTH || !isObject(input)) {
             return 1;
+        }
         const cached = counts.get(input)?.get(level);
-        if (cached !== undefined)
+        if (cached !== undefined) {
             return cached;
+        }
         const schema = getResolvedRef(input, mergeSiblingReferences);
-        if (!isObject(schema))
+        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))
+        if (schema.example !== undefined || (Array.isArray(schema.examples) && schema.examples.length > 0)) {
             return 1;
+        }
         let total = 1;
         const add = (child) => {
-            if (total <= limit)
+            if (total <= limit) {
                 total += count(child, level + 1);
+            }
         };
-        if (isObject(schema.properties))
+        if (isObject(schema.properties)) {
             Object.values(schema.properties).forEach(add);
-        if (isObject(schema.patternProperties))
+        }
+        if (isObject(schema.patternProperties)) {
             Object.values(schema.patternProperties).forEach(add);
-        if (isObject(schema.additionalProperties))
+        }
+        if (isObject(schema.additionalProperties)) {
             add(schema.additionalProperties);
-        if (schema.items !== undefined)
+        }
+        if (schema.items !== undefined) {
             add(schema.items);
-        if (Array.isArray(schema.prefixItems))
+        }
+        if (Array.isArray(schema.prefixItems)) {
             schema.prefixItems.forEach(add);
-        if (Array.isArray(schema.allOf))
+        }
+        if (Array.isArray(schema.allOf)) {
             schema.allOf.forEach(add);
-        const variants = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : [];
+        }
+        const anyOf = Array.isArray(schema.anyOf) ? schema.anyOf : [];
+        const variants = Array.isArray(schema.oneOf) ? schema.oneOf : 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) => {
@@ -57,8 +69,9 @@ export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_
             : [variants[0], nonNull];
         let variantCount = 0;
         for (const candidate of candidates) {
-            if (candidate !== undefined && total <= limit && variantCount <= limit)
+            if (candidate !== undefined && total <= limit && variantCount <= limit) {
                 variantCount = Math.max(variantCount, count(candidate, level + 1));
+            }
         }
         total += variantCount;
         const levels = counts.get(input) ?? new Map();
@@ -72,40 +85,51 @@ export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_
 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, linked = false) => {
-    if (source.example !== undefined)
+    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))
+            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)
+            if (example.value !== undefined) {
                 return [{ ...metadata, value: example.value }];
-            if (/^3\.2\./.test(openapiVersion) && typeof example.serializedValue === 'string')
+            }
+            if (/^3\.2\./.test(openapiVersion) && typeof example.serializedValue === 'string') {
                 return [{ ...metadata, serializedValue: example.serializedValue }];
-            if (typeof example.externalValue === 'string')
+            }
+            if (typeof example.externalValue === 'string') {
                 return [{ ...metadata, externalValue: example.externalValue }];
-            if (/^3\.2\./.test(openapiVersion) && example.dataValue !== undefined)
+            }
+            if (/^3\.2\./.test(openapiVersion) && example.dataValue !== undefined) {
                 return [{ ...metadata, dataValue: example.dataValue }];
+            }
             return [];
         });
     }
     const schema = getResolvedRef(source.schema, mergeSiblingReferences);
-    if (!isObject(schema))
+    if (!isObject(schema)) {
         return [];
-    if (schema.example !== undefined)
+    }
+    if (schema.example !== undefined) {
         return [{ value: schema.example }];
-    if (Array.isArray(schema.examples) && schema.examples.length)
+    }
+    if (Array.isArray(schema.examples) && schema.examples.length) {
         return schema.examples.map((value) => ({ value }));
-    if (linked)
+    }
+    if (linked) {
         return [];
-    if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES)
+    }
+    if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES) {
         return [{ omitted: true }];
+    }
     if (isXmlMediaType(mediaType)) {
         const result = getXmlBodyExample(source.schema, undefined, {
             mode,

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 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 { DocumentLoadOptions } from './load-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,sBAAsB,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,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/load-document.d.ts

@@ -1,4 +1,11 @@
 import { type OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+/** Permissions for loading an API description and its external references. */
+export type DocumentLoadOptions = {
+    /** Allow private-network requests only for trusted input. Defaults to false. */
+    allowPrivateNetworks?: boolean;
+    /** Approved directory for local files and references. File access is disabled when omitted. */
+    basePath?: string;
+};
 /** Coerce one plain document and keep references linked to shared targets. */
-export declare const loadDocument: (input: OpenApiDocument | Record<string, unknown> | string) => Promise<OpenApiDocument>;
+export declare const loadDocument: (input: OpenApiDocument | Record<string, unknown> | string, options?: DocumentLoadOptions) => Promise<OpenApiDocument>;
 //# sourceMappingURL=load-document.d.ts.map

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,EAErB,MAAM,8DAA8D,CAAA;AA6LrE,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,KACxD,OAAO,CAAC,eAAe,CAgGzB,CAAA"}
+{"version":3,"file":"load-document.d.ts","sourceRoot":"","sources":["../src/load-document.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,8DAA8D,CAAA;AAiMrE,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG;IAChC,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EACzD,UAAS,mBAAwB,KAChC,OAAO,CAAC,eAAe,CAoGzB,CAAA"}

package/dist/load-document.js

@@ -40,8 +40,9 @@ const attachRefValues = (document, schemas = getSchemas(document), { detectOnly
             kind = kind && getChildKind(kind, key);
             position = Array.isArray(parent) ? position : position && getChildPosition(position, key);
             // Arbitrary extension and example data has not passed an OpenAPI object schema.
-            if (position === 'document' && kind === undefined)
+            if (position === 'document' && kind === undefined) {
                 position = undefined;
+            }
             parent = getValueByPath(parent, [key]).value;
         }
         const schema = getTargetSchema(position, kind);
@@ -78,15 +79,20 @@ const attachRefValues = (document, schemas = getSchemas(document), { detectOnly
             // support summary and description; casting them as their targets would add defaults.
             // Path Item Objects declare their own $ref field, so their siblings are cast normally.
             const reference = typeof value.$ref === 'string' ? value.$ref : undefined;
-            const cast = reference === undefined || schema === referenceTargetSchemas.pathItem
-                ? coerceValue(schema, value)
-                : position === 'schema'
-                    ? { ...coerceValue(SchemaObjectSchema, value), $ref: reference }
-                    : {
-                        $ref: reference,
-                        ...(typeof value.summary === 'string' ? { summary: value.summary } : {}),
-                        ...(typeof value.description === 'string' ? { description: value.description } : {}),
-                    };
+            let cast;
+            if (reference === undefined || schema === referenceTargetSchemas.pathItem) {
+                cast = coerceValue(schema, value);
+            }
+            else if (position === 'schema') {
+                cast = { ...coerceValue(SchemaObjectSchema, value), $ref: reference };
+            }
+            else {
+                cast = {
+                    $ref: reference,
+                    ...(typeof value.summary === 'string' ? { summary: value.summary } : {}),
+                    ...(typeof value.description === 'string' ? { description: value.description } : {}),
+                };
+            }
             if (fallback?.booleanSchemas) {
                 restoreBooleanSchemas(value, cast, position);
             }
@@ -147,9 +153,12 @@ const attachRefValues = (document, schemas = getSchemas(document), { detectOnly
     return hasExternalReferences;
 };
 /** Coerce one plain document and keep references linked to shared targets. */
-export const loadDocument = async (input) => {
+export const loadDocument = async (input, options = {}) => {
     let raw;
     let origin;
+    const { fetchUrls, readFiles } = await import('@scalar/json-magic/bundle/plugins/node');
+    const urlLoader = fetchUrls({ blockPrivateNetworks: !options.allowPrivateNetworks });
+    const fileLoader = options.basePath === undefined ? undefined : readFiles({ basePath: options.basePath });
     // Reference links are attached below, so never mutate the caller's document.
     if (typeof input !== 'string') {
         raw = deepClone(getRaw(input));
@@ -161,17 +170,24 @@ export const loadDocument = async (input) => {
             raw = normalized;
         }
         else if (/^https?:\/\//i.test(input)) {
-            const response = await fetch(input);
-            if (!response.ok) {
-                throw new Error(`Failed to load OpenAPI document (HTTP ${response.status})`);
+            const result = await urlLoader.exec(input);
+            if (!result.ok) {
+                throw new Error('Failed to load OpenAPI document');
             }
-            raw = normalize(await response.text());
+            raw = result.data;
             origin = input;
         }
         else {
-            const [{ resolve }, { readFile }] = await Promise.all([import('node:path'), import('node:fs/promises')]);
+            if (!fileLoader) {
+                throw new Error('Local file access requires an explicit basePath');
+            }
+            const { resolve } = await import('node:path');
             origin = resolve(input);
-            raw = normalize(await readFile(origin, 'utf8'));
+            const result = await fileLoader.exec(origin);
+            if (!result.ok) {
+                throw new Error('Failed to load OpenAPI document');
+            }
+            raw = result.data;
         }
     }
     if (!isObject(raw)) {
@@ -187,12 +203,7 @@ export const loadDocument = async (input) => {
     // Resolve external targets only when the initial local-reference pass finds them.
     if (hasExternalReferences) {
         const errors = [];
-        const plugins = typeof process === 'undefined'
-            ? [(await import('@scalar/json-magic/bundle/plugins/browser')).fetchUrls()]
-            : [
-                (await import('@scalar/json-magic/bundle/plugins/node')).fetchUrls(),
-                (await import('@scalar/json-magic/bundle/plugins/node')).readFiles(),
-            ];
+        const plugins = fileLoader ? [urlLoader, fileLoader] : [urlLoader];
         document = await bundle(upgraded, {
             plugins,
             origin,

package/dist/markdown/index.d.ts

@@ -0,0 +1,5 @@
+/** Format-neutral Markdown building blocks shared by API description renderers. */
+export { anchor, createDocumentAnchors } from '../document-anchors.js';
+export { describe, field, heading, inlineCode, item, link, list, paragraph, strong, text } from '../markdown-nodes.js';
+export { createDescriptionParser, expandDescriptions } from '../parse-description.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/markdown/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/markdown/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAEnF,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AACnE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACnH,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/markdown/index.js

@@ -0,0 +1,4 @@
+/** Format-neutral Markdown building blocks shared by API description renderers. */
+export { anchor, createDocumentAnchors } from '../document-anchors.js';
+export { describe, field, heading, inlineCode, item, link, list, paragraph, strong, text } from '../markdown-nodes.js';
+export { createDescriptionParser, expandDescriptions } from '../parse-description.js';

package/dist/markdown-nodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-nodes.d.ts","sourceRoot":"","sources":["../src/markdown-nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,OAAO,EACP,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,SAAS,EACT,eAAe,EACf,MAAM,EACN,IAAI,EACL,MAAM,OAAO,CAAA;AAEd;;;GAGG;AACH,KAAK,sBAAsB,GAAG,IAAI,GAAG;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtF,OAAO,QAAQ,OAAO,CAAC;IACrB,UAAU,eAAe;QACvB,sBAAsB,EAAE,sBAAsB,CAAA;KAC/C;IACD,UAAU,cAAc;QACtB,sBAAsB,EAAE,sBAAsB,CAAA;KAC/C;CACF;AAED,gGAAgG;AAChG,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,IAGpC,CAAA;AACF,uDAAuD;AACvD,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,UAAkE,CAAA;AAC9G,iDAAiD;AACjD,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,eAAe,EAAE,KAAG,SAA8C,CAAA;AACzG,qCAAqC;AACrC,eAAO,MAAM,MAAM,GAAI,GAAG,UAAU,eAAe,EAAE,KAAG,MAAwC,CAAA;AAChG,oEAAoE;AACpE,eAAO,MAAM,QAAQ,GAAI,GAAG,UAAU,eAAe,EAAE,KAAG,QAA4C,CAAA;AACtG,mCAAmC;AACnC,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,UAAU,eAAe,EAAE,KAAG,OAIhF,CAAA;AACF,4DAA4D;AAC5D,eAAO,MAAM,IAAI,GAAI,GAAG,UAAU,QAAQ,CAAC,UAAU,CAAC,KAAG,QAA2D,CAAA;AACpH,mCAAmC;AACnC,eAAO,MAAM,IAAI,GAAI,UAAU,QAAQ,EAAE,KAAG,IAAmE,CAAA;AAC/G;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,MAIrC,CAAA;AACD,8EAA8E;AAC9E,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,KAAG,IAAsE,CAAA;AACxH,oFAAoF;AACpF,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,EAAE,OAAO,eAAe,KAAG,QACK,CAAA;AACnE,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,sBAAsB,EAC8B,CAAA"}
+{"version":3,"file":"markdown-nodes.d.ts","sourceRoot":"","sources":["../src/markdown-nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,OAAO,EACP,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,SAAS,EACT,eAAe,EACf,MAAM,EACN,IAAI,EACL,MAAM,OAAO,CAAA;AAEd;;;GAGG;AACH,KAAK,sBAAsB,GAAG,IAAI,GAAG;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtF,OAAO,QAAQ,OAAO,CAAC;IACrB,UAAU,eAAe;QACvB,sBAAsB,EAAE,sBAAsB,CAAA;KAC/C;IACD,UAAU,cAAc;QACtB,sBAAsB,EAAE,sBAAsB,CAAA;KAC/C;CACF;AAED,gGAAgG;AAChG,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,IAGpC,CAAA;AACF,uDAAuD;AACvD,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,UAAkE,CAAA;AAC9G,iDAAiD;AACjD,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,eAAe,EAAE,KAAG,SAA8C,CAAA;AACzG,qCAAqC;AACrC,eAAO,MAAM,MAAM,GAAI,GAAG,UAAU,eAAe,EAAE,KAAG,MAAwC,CAAA;AAChG,oEAAoE;AACpE,eAAO,MAAM,QAAQ,GAAI,GAAG,UAAU,eAAe,EAAE,KAAG,QAA4C,CAAA;AACtG,mCAAmC;AACnC,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,UAAU,eAAe,EAAE,KAAG,OAIhF,CAAA;AACF,4DAA4D;AAC5D,eAAO,MAAM,IAAI,GAAI,GAAG,UAAU,QAAQ,CAAC,UAAU,CAAC,KAAG,QAA2D,CAAA;AACpH,mCAAmC;AACnC,eAAO,MAAM,IAAI,GAAI,UAAU,QAAQ,EAAE,KAAG,IAAmE,CAAA;AAC/G;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,MAKrC,CAAA;AACD,8EAA8E;AAC9E,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,KAAG,IAAsE,CAAA;AACxH,oFAAoF;AACpF,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,EAAE,OAAO,eAAe,KAAG,QACK,CAAA;AACnE,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,sBAAsB,EAC8B,CAAA"}

package/dist/markdown-nodes.js

@@ -26,6 +26,7 @@ export const list = (children) => ({ type: 'list', ordered: false, spread: false
  * additional schemes and excludes IRC/XMPP, so it is not compatible here.
  */
 export const safeUrl = (url) => {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: Control characters are intentionally matched to validate or sanitize input.
     const normalized = url.replace(/[\u0000-\u0020\u007f-\u009f]/g, '');
     const protocol = /^([^/?#]*):/.exec(normalized)?.[1];
     return protocol && !['http', 'https', 'irc', 'ircs', 'mailto', 'xmpp'].includes(protocol.toLowerCase()) ? '' : url;

package/dist/parse-description.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-description.d.ts","sourceRoot":"","sources":["../src/parse-description.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,WAAW,EAAE,MAAM,OAAO,CAAA;AAkF7D,0FAA0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;AAE1E,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,QAAO,CAAC,MAAM,iBAAiB,CA4ClE,CAAA;AAED,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,GAAU,OAAO,WAAW,EAAE,EAAE,aAAa,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAe3G,CAAA"}
+{"version":3,"file":"parse-description.d.ts","sourceRoot":"","sources":["../src/parse-description.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,WAAW,EAAE,MAAM,OAAO,CAAA;AAsG7D,0FAA0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;AAE1E,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,QAAO,CAAC,MAAM,iBAAiB,CAuDlE,CAAA;AAED,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,GAAU,OAAO,WAAW,EAAE,EAAE,aAAa,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAkB3G,CAAA"}