@scalar/openapi-to-markdown 1.5.4 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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

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/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;AAiMrE,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

@@ -153,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));
@@ -167,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)) {
@@ -193,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/render-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,8DAA8D,CAAA;AAcrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAwD7D,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,MAAM,CAAC,CA0RnB,CAAA"}
+{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,8DAA8D,CAAA;AAerE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAwD7D,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,MAAM,CAAC,CAyRnB,CAAA"}

package/dist/render-document.js

@@ -12,6 +12,7 @@ import { renderExamples } from './render-examples.js';
 import { formatOperationMethod, renderOperation } from './render-operation.js';
 import { createSchemaRenderer } from './render-schema.js';
 import { renderSecurity } from './render-security.js';
+import { getTagSections } from './render-tags.js';
 const serializer = unified()
     .use(remarkGfm)
     .use(remarkStringify, {
@@ -185,8 +186,7 @@ export const createDocumentRenderer = () => {
             nodes.push(...(await renderSecurity(document.security, document.components?.securitySchemes, description, 2)));
             if (document.tags?.length) {
                 nodes.push(heading(2, text('Tags')));
-                for (const tag of document.tags) {
-                    const title = /^3\.2\./.test(openapiVersion) ? (tag.summary ?? tag.name) : tag.name;
+                for (const { tag, title } of getTagSections(document.tags, openapiVersion)) {
                     nodes.push(heading(3, text(title)), ...(await description(tag.description)));
                     if (tag.externalDocs) {
                         nodes.push(paragraph(link(tag.externalDocs.url, tag.externalDocs.description ?? tag.externalDocs.url)));

package/dist/render-tags.d.ts

@@ -0,0 +1,7 @@
+import type { TagObject } from '@scalar/workspace-store/schemas/v3.2/strict/tag';
+/** Keep tag ancestry visible without exceeding Markdown's six heading levels. */
+export declare const getTagSections: (tags: TagObject[], openapiVersion: string) => {
+    tag: TagObject;
+    title: string;
+}[];
+//# sourceMappingURL=render-tags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-tags.d.ts","sourceRoot":"","sources":["../src/render-tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iDAAiD,CAAA;AAEhF,iFAAiF;AACjF,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,EAAE,EAAE,gBAAgB,MAAM,KAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAwE3G,CAAA"}

package/dist/render-tags.js

@@ -0,0 +1,73 @@
+/** Keep tag ancestry visible without exceeding Markdown's six heading levels. */
+export const getTagSections = (tags, openapiVersion) => {
+    const nested = /^3\.2\./.test(openapiVersion);
+    const label = (tag) => (nested ? (tag.summary ?? tag.name) : tag.name);
+    const byName = new Map(tags.map((tag) => [tag.name, tag]));
+    // Duplicate names cannot identify a parent unambiguously. Preserve every declaration.
+    if (!nested || byName.size !== tags.length) {
+        return tags.map((tag) => ({ tag, title: label(tag) }));
+    }
+    const titles = new Map();
+    const parents = new Map();
+    const invalid = new Set();
+    for (const tag of tags) {
+        const chain = [];
+        const seen = new Set();
+        const pending = [tag];
+        while (pending.length) {
+            const current = pending.pop();
+            if (seen.has(current.name) || invalid.has(current.name)) {
+                // Invalid cycles and chains leading into them stay flat, like reference navigation.
+                for (const member of chain) {
+                    titles.set(member.name, label(member));
+                    invalid.add(member.name);
+                }
+                break;
+            }
+            if (titles.has(current.name)) {
+                break;
+            }
+            seen.add(current.name);
+            chain.push(current);
+            const parent = current.parent === undefined ? undefined : byName.get(current.parent);
+            if (parent) {
+                pending.push(parent);
+            }
+        }
+        for (const current of chain.reverse()) {
+            if (titles.has(current.name)) {
+                continue;
+            }
+            const parentTitle = current.parent === undefined ? undefined : titles.get(current.parent);
+            titles.set(current.name, parentTitle === undefined ? label(current) : `${parentTitle} › ${label(current)}`);
+            if (parentTitle !== undefined && current.parent !== undefined) {
+                parents.set(current.name, current.parent);
+            }
+        }
+    }
+    const children = new Map();
+    const roots = [];
+    for (const tag of tags) {
+        const parent = parents.get(tag.name);
+        if (parent === undefined) {
+            roots.push(tag);
+        }
+        else {
+            const siblings = children.get(parent) ?? [];
+            siblings.push(tag);
+            children.set(parent, siblings);
+        }
+    }
+    const sections = [];
+    const pending = roots.reverse();
+    while (pending.length) {
+        const tag = pending.pop();
+        sections.push({ tag, title: titles.get(tag.name) });
+        // Use a stack instead of recursion so deeply nested descriptions cannot exhaust the call stack.
+        const siblings = children.get(tag.name) ?? [];
+        for (const child of [...siblings].reverse()) {
+            pending.push(child);
+        }
+    }
+    return sections;
+};

package/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.5.4",
+  "version": "1.6.0",
   "engines": {
     "node": ">=22"
   },
@@ -33,6 +33,11 @@
       "import": "./dist/browser.js",
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.js"
+    },
+    "./markdown": {
+      "import": "./dist/markdown/index.js",
+      "types": "./dist/markdown/index.d.ts",
+      "default": "./dist/markdown/index.js"
     }
   },
   "files": [
@@ -40,11 +45,11 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@scalar/code-highlight": "0.4.9",
-    "@scalar/helpers": "0.16.3",
-    "@scalar/json-magic": "0.15.7",
-    "@scalar/openapi-upgrader": "0.4.4",
-    "@scalar/workspace-store": "0.68.3",
+    "@scalar/code-highlight": "0.4.10",
+    "@scalar/helpers": "0.16.4",
+    "@scalar/json-magic": "0.16.0",
+    "@scalar/openapi-upgrader": "0.4.5",
+    "@scalar/workspace-store": "0.68.4",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",
@@ -54,9 +59,9 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@scalar/components": "0.31.1",
-    "@scalar/galaxy": "0.7.1",
-    "@scalar/themes": "0.19.1",
+    "@scalar/components": "0.32.0",
+    "@scalar/galaxy": "0.7.2",
+    "@scalar/themes": "0.19.2",
     "@tailwindcss/vite": "^4.3.3",
     "@types/mdast": "^4.0.4",
     "@vitejs/plugin-vue": "^6.0.8",