@scalar/openapi-to-markdown 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @scalar/openapi-to-markdown
 
+## 1.5.0
+
+### Minor Changes
+
+- [#10425](https://github.com/scalar/scalar/pull/10425): Make single-page Markdown easier to read, especially for AI agents reading `llms.txt` exports.
+  - An operation, webhook or model page now starts with that item as its `#` title and uses `##` sections, without the API's document header. An empty API version is never printed.
+  - Schema property descriptions keep their Markdown: paragraphs, links, inline code and fenced code blocks are no longer flattened into one escaped line. A parameter description is no longer repeated by its schema.
+  - Each property is one line with its name, type and annotations. Nullable unions read as `string | null`, single-branch `allOf` wrappers as the wrapped type, unions of plain types as one type, `const` and `enum` schemas without a `type` as their inferred JSON type, and arrays of simple items as `array of …`. Composition branches are listed one per item, with discriminator values beside their branch.
+  - Parameters are grouped by location. Responses that return the same schema and media type are grouped into one entry, such as a list of error statuses.
+  - In linked mode, references are shown as a link in the property's type. Primitive, enum and `const` schemas and aliases of them are written in place instead of linked; set `schemaReferences.inlinePrimitives: false` to link them. Generated examples are left out without a placeholder, while a model page generates an example of its own schema with linked schemas as empty stubs.
+  - The Authentication section is left out when the API description declares no security requirements, and only an explicit `security: []` says that no authentication is required. Security schemes are summarized on one line, for example "API key in header `X-Api-Key`", instead of printed as JSON.
+  - Selected pages retain empty server overrides as `/` and include server variable choices and descriptions. Model pages retain authored examples for primitive and array schemas as well as objects.
+
+- [#10425](https://github.com/scalar/scalar/pull/10425): Give shared schemas canonical definitions and internal links in whole-document Markdown exports, retaining primitive types inline and constraints beside references.
+
+  Deduplicate generated examples within each schema and request/response/media-type context, label them as generated, and retain authored examples at their original locations.
+
+  Explain inherited servers and authentication once, with links from operations, while retaining path and operation overrides, server variables, and explicit anonymous access.
+
+  Add a compact contents index linking to operations, webhooks, and schemas through unique explicit anchors.
+
+### Patch Changes
+
+- [#10425](https://github.com/scalar/scalar/pull/10425): Add a browser playground for previewing and downloading per-page, linked, and whole-document Markdown exports from Galaxy, Stripe, GitHub, and Cloudflare examples.
+- [#10425](https://github.com/scalar/scalar/pull/10425): Shorten the `## Schemas` section for schemas a page already expanded. Such a model is now a single line, for example `` `Customer` — shown above. ``, instead of a heading, type, "shown above" note and generated example. The line keeps the model's title and any description that a reference sibling replaced where the schema was expanded. A selected model, leaf schemas, models the page has not expanded, and object models with authored examples keep their full sections. A Stripe operation page such as `GET /v1/customers/{customer}` drops from about 2.5 MB to about 1.3 MB, with 819 of its 918 model sections reduced to one line. Everything above `## Schemas` is unchanged.
+
 ## 1.4.0
 
 ### Minor Changes

package/README.md

@@ -130,6 +130,15 @@ It preserves Markdown descriptions, GFM tables and code blocks without rendering
 or converting the generated document through HTML. Descriptions containing raw HTML or
 Scalar alerts use a separate sanitization and conversion path. Images remain excluded.
 
+Each schema property is one line with its name, type and annotations, for example
+`` **`archived_at` (required)**: `string | null`, format: `date-time` ``, followed by
+its description with its paragraphs, links and code blocks intact. Nullable unions,
+single-branch `allOf` wrappers and unions of plain types are labelled as one type.
+Parameters are listed by location. Responses that return the same schema and media
+type share one entry, such as a list of error statuses. Security schemes are
+summarized on one line, and an Authentication section appears only when the API
+description declares requirements.
+
 Schema normalization and description parsing are cached within each renderer. Recursive
 schema expansion still tracks ancestors and stops at a depth of ten. Output may use tighter
 list spacing and normalized Markdown escaping compared with earlier versions.
@@ -167,15 +176,35 @@ await createMarkdownFromOpenApi(content, {
 - **Webhook:** One operation selected by its exact OpenAPI webhook name and method, including parameters, payload and responses. The name is a label, not a delivery URL.
 - **Introduction:** API title, versions, description, contact, license, terms of service, servers and global authentication requirements. No operations, tags, models or webhooks.
 
-Selected pages retain API title, versions and description. They exclude unrelated reference content. Operation servers override path servers, which override document servers. Operation security overrides document security, including `security: []` for anonymous access. Parameter overrides use the parameter name and location. Required schemas are collected after reference resolution, so dependencies remain available even when their original section is omitted.
+An operation, webhook or model page starts with that item as its `#` title, with its sections (parameters, request body, responses) as `##` headings. It leaves out the API title, versions and description, which belong on the introduction page. Tag and whole-document exports keep the document header. Selected pages exclude unrelated reference content. Operation servers override path servers, which override document servers. Operation security overrides document security, including `security: []` for anonymous access. Parameter overrides use the parameter name and location. Required schemas are collected after reference resolution, so dependencies remain available even when their original section is omitted.
 
 Omitting options, or passing `{}`, renders the whole document. OpenAPI 2.0 inputs are migrated before selection: use definition names with `model`. Webhooks require OpenAPI 3.1 or later.
 
+Whole-document exports include a compact contents index after the introduction, linking
+to operations by method and path, webhooks, and component schemas. Empty groups are omitted.
+
+Whole-document exports render each named structured schema once under `## Schemas`.
+Operations and nested properties link to that section, while simple primitive references
+remain inline. Generated explicit anchors keep links stable even when schema titles repeat.
+The export is self-contained; a supplied `schemaReferences.resolveUrl` callback still controls
+reference URLs when linked mode is explicitly requested.
+
+Within a whole-document export, repeated generated examples link to their first
+occurrence. Request, response, and media-type contexts remain distinct. Synthesized
+values are labeled **Generated example**, and authored examples remain at every
+usage, including all values in a schema's `examples` array.
+
+Global servers and authentication are documented once. Operations link to inherited
+defaults and show their own overrides in full. Path-level servers are explained at
+their first use and linked thereafter, including variable defaults, choices, and
+descriptions. Explicit empty server overrides use `/`; explicit `security: []` remains
+anonymous. Absent security requirements do not imply anonymous access.
+
 ### Errors and limitations
 
 Invalid, combined, or missing selectors reject the returned promise with an error. Duplicate operation IDs are ambiguous and list matching paths and methods; use a path/method selector instead. Duplicate tag declarations are also rejected. Names are case sensitive. Operation JSON pointers must target `/paths/{path}/{method}`, with an optional leading `#` and standard `~0`/`~1` escaping.
 
-Selection does not add support for every OpenAPI or JSON Schema keyword. Callbacks are not selectable pages. External references follow the existing workspace loader behavior. Recursive schema expansion stops on a repeated ancestor, with a depth limit of ten as a fallback. Shared dependencies have one component section, but may also appear inline where used. Authentication lists alternatives separately; schemes within one requirement must be used together.
+Selection does not add support for every OpenAPI or JSON Schema keyword. Callbacks are not selectable pages. External references follow the existing workspace loader behavior. Recursive schema expansion stops on a repeated ancestor, with a depth limit of ten as a fallback. Selected-page exports expand shared dependencies once, where they are first used. Whole-document exports instead link structured dependencies to their full definitions under `## Schemas`. For selected-page exports, the `## Schemas` section lists a component the page already expanded on one line, with its title and any description that a reference sibling replaced, and keeps a full section for the selected model, for leaf schemas, for models the page has not expanded yet, and for object models with authored examples. Authentication lists alternatives separately; schemes within one requirement must be used together.
 
 ### Copying Markdown in the browser
 
@@ -237,11 +266,43 @@ method: 'post' } }`, the one-shot `createMarkdownFromOpenApi`, or the browser en
 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
+References to primitive, enum and `const` schemas, and to aliases of them, are
+written in place, because their whole definition fits on one line. Pass
+`inlinePrimitives: false` to link them too. Object, array and composition schemas
+are always linked.
+
+Linked mode uses authored media-type and schema examples and does not generate
+examples on operation pages, which would expand every linked schema. A model page
+generates an example for its own schema, with linked schemas left as empty
+stubs. Authored examples are not capped in size. 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.
+
+## Browser playground
+
+From the repository root, run:
+
+```sh
+pnpm --filter @scalar/openapi-to-markdown dev
+```
+
+Open `http://localhost:3000` (or the address printed by Vite). Choose Galaxy,
+Stripe, GitHub, or Cloudflare, then preview a **Per-page**, **Linked page**, or
+**Full export**. Page selection includes operations by method/path, models,
+webhooks, tags, and the introduction. Search the page list to find an item.
+
+The **Preview** and **Markdown** views show the rendered document and its exact
+source. Copy or download the Markdown, follow internal links in whole exports,
+or follow linked schema URLs to open that model in the playground. The additional
+**Link shared schemas** control also allows a linked full export.
+
+Galaxy is included locally through `@scalar/galaxy`; the other examples fetch
+current documents from their official GitHub repositories and require internet
+access on first load. Loading and exporting happen on the development server.
+It retains one resolved document at a time; switching examples releases the previous
+renderer. Large exports can take longer. The reported duration measures Markdown
+export, excluding document loading and HTML preview conversion. `/llms.txt` still
+serves the complete Galaxy Markdown export.

package/dist/document-anchors.d.ts

@@ -0,0 +1,8 @@
+import type { Html } from 'mdast';
+/** One export owns its destinations, so repeated titles and concurrent renders cannot collide. */
+export declare const createDocumentAnchors: () => {
+    get: (kind: string, identity: string, label?: string) => string;
+};
+/** Explicit destinations do not depend on a Markdown viewer's heading slug rules. */
+export declare const anchor: (id: string) => Html;
+//# sourceMappingURL=document-anchors.d.ts.map

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

@@ -0,0 +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"}

package/dist/document-anchors.js

@@ -0,0 +1,25 @@
+import { slugger } from '@scalar/helpers/string/slugger';
+/** One export owns its destinations, so repeated titles and concurrent renders cannot collide. */
+export const createDocumentAnchors = () => {
+    const slugs = slugger();
+    const ids = new Map();
+    const used = new Set();
+    return {
+        get: (kind, identity, label = identity) => {
+            const key = JSON.stringify([kind, identity]);
+            const previous = ids.get(key);
+            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))
+                id = slugs.slug(base);
+            used.add(id);
+            ids.set(key, id);
+            return id;
+        },
+    };
+};
+/** Explicit destinations do not depend on a Markdown viewer's heading slug rules. */
+export const anchor = (id) => ({ type: 'html', value: `<a id="${id}"></a>` });

package/dist/document-examples.d.ts

@@ -0,0 +1,14 @@
+import type { Code } from 'mdast';
+import type { createDocumentAnchors } from './document-anchors.js';
+import { type ExampleSource, getMarkdownExamples } from './get-markdown-examples.js';
+/** Generation and destinations are shared only within one whole-document export. */
+export type DocumentExamples = {
+    get: typeof getMarkdownExamples;
+    show: (source: ExampleSource, scope: string, code: Code) => {
+        id: string;
+        previous: boolean;
+    };
+};
+/** Reuse generation by schema and context; deduplicate only after comparing the serialized example. */
+export declare const createDocumentExamples: (anchors: ReturnType<typeof createDocumentAnchors>) => DocumentExamples;
+//# sourceMappingURL=document-examples.d.ts.map

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

@@ -0,0 +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"}

package/dist/document-examples.js

@@ -0,0 +1,54 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+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))
+        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;
+};
+/** Reuse generation by schema and context; deduplicate only after comparing the serialized example. */
+export const createDocumentExamples = (anchors) => {
+    const cache = new Map();
+    const shown = new WeakMap();
+    let cachedCount = 0;
+    let nextId = 0;
+    return {
+        get: (...args) => {
+            const [source, ...settings] = args;
+            const schema = identity(source);
+            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)
+                return previous;
+            // Large APIs must not retain every generated object until the export finishes.
+            if (cachedCount >= 256) {
+                cache.clear();
+                cachedCount = 0;
+            }
+            const entries = cache.get(schema) ?? new Map();
+            const examples = getMarkdownExamples(...args);
+            entries.set(scope, examples);
+            cache.set(schema, entries);
+            cachedCount++;
+            return examples;
+        },
+        show: (source, scope, code) => {
+            const schema = identity(source);
+            const entries = schema ? (shown.get(schema) ?? new Map()) : new Map();
+            const previous = entries.get(scope);
+            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)
+                shown.set(schema, entries);
+            return { id, previous: false };
+        },
+    };
+};

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

@@ -9,6 +9,8 @@ type MarkdownExample = {
     name?: string;
     summary?: string;
     description?: string;
+    /** Authored examples stay local; only synthesized fallbacks can be deduplicated. */
+    generated?: boolean;
 } & ({
     value: unknown;
 } | {

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,EACrC,gBAAc,KACb,eAAe,EA2CjB,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,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"}

package/dist/get-markdown-examples.js

@@ -95,18 +95,15 @@ schemaOpenapiVersion = openapiVersion, linked = false) => {
             return [];
         });
     }
-    const schema = linked
-        ? getResolvedRef(source.schema, mergeSiblingReferences)
-        : getResolvedRef(source.schema);
+    const schema = getResolvedRef(source.schema, mergeSiblingReferences);
     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 (schema.example !== undefined)
+        return [{ value: schema.example }];
+    if (Array.isArray(schema.examples) && schema.examples.length)
+        return schema.examples.map((value) => ({ value }));
+    if (linked)
+        return [];
     if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES)
         return [{ omitted: true }];
     if (isXmlMediaType(mediaType)) {
@@ -115,11 +112,13 @@ schemaOpenapiVersion = openapiVersion, linked = false) => {
             openapiVersion: schemaOpenapiVersion,
         });
         return [
-            result.xml === undefined ? { error: 'Unable to generate an XML example.' } : { serializedValue: result.xml },
+            result.xml === undefined
+                ? { error: 'Unable to generate an XML example.', generated: true }
+                : { serializedValue: result.xml, generated: true },
         ];
     }
     const value = getExampleFromSchema(getResolvedRef(source.schema, mergeSiblingReferences), {
         mode,
     });
-    return value === undefined ? [] : [{ value }];
+    return value === undefined ? [] : [{ value, generated: true }];
 };

package/dist/markdown-nodes.d.ts

@@ -1,4 +1,20 @@
-import type { Heading, InlineCode, Link, List, ListItem, Paragraph, PhrasingContent, Strong, Text } from 'mdast';
+import type { Emphasis, Heading, InlineCode, Link, List, ListItem, Node, Paragraph, PhrasingContent, Strong, Text } from 'mdast';
+/**
+ * A description that still has to be parsed as Markdown. Schema rendering is synchronous and
+ * description parsing is not, so the page renderer replaces these before it serializes a page.
+ */
+type DescriptionPlaceholder = Node & {
+    type: 'descriptionPlaceholder';
+    value: string;
+};
+declare module 'mdast' {
+    interface BlockContentMap {
+        descriptionPlaceholder: DescriptionPlaceholder;
+    }
+    interface RootContentMap {
+        descriptionPlaceholder: DescriptionPlaceholder;
+    }
+}
 /** Collapse HTML-style inline whitespace; the serializer escapes generated text as Markdown. */
 export declare const text: (value: unknown) => Text;
 /** Inline code fences are chosen by the serializer. */
@@ -7,6 +23,8 @@ export declare const inlineCode: (value: unknown) => InlineCode;
 export declare const paragraph: (...children: PhrasingContent[]) => Paragraph;
 /** Construct an emphasized label. */
 export declare const strong: (...children: PhrasingContent[]) => Strong;
+/** Construct emphasized text, for notes about the output itself. */
+export declare const emphasis: (...children: PhrasingContent[]) => Emphasis;
 /** Construct a section heading. */
 export declare const heading: (depth: Heading["depth"], ...children: PhrasingContent[]) => Heading;
 /** Construct a list item that may contain nested blocks. */
@@ -22,4 +40,7 @@ export declare const safeUrl: (url: string) => string;
 export declare const link: (url: string, label: string) => Link;
 /** Render a metadata label and value with the established nonbreaking separator. */
 export declare const field: (label: string, value: PhrasingContent) => ListItem;
+/** Defer a description, so it keeps its paragraphs, links and code blocks once parsed. */
+export declare const describe: (value: unknown) => DescriptionPlaceholder[];
+export {};
 //# sourceMappingURL=markdown-nodes.d.ts.map

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,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEhH,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,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"}
+{"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"}

package/dist/markdown-nodes.js

@@ -9,6 +9,8 @@ export const inlineCode = (value) => ({ type: 'inlineCode', value: String(value
 export const paragraph = (...children) => ({ type: 'paragraph', children });
 /** Construct an emphasized label. */
 export const strong = (...children) => ({ type: 'strong', children });
+/** Construct emphasized text, for notes about the output itself. */
+export const emphasis = (...children) => ({ type: 'emphasis', children });
 /** Construct a section heading. */
 export const heading = (depth, ...children) => ({
     type: 'heading',
@@ -32,3 +34,5 @@ export const safeUrl = (url) => {
 export const link = (url, label) => ({ type: 'link', url: safeUrl(url), children: [text(label)] });
 /** Render a metadata label and value with the established nonbreaking separator. */
 export const field = (label, value) => item(paragraph(strong(text(`${label}:`)), text('\u00a0'), value));
+/** Defer a description, so it keeps its paragraphs, links and code blocks once parsed. */
+export const describe = (value) => typeof value === 'string' && value.trim() ? [{ type: 'descriptionPlaceholder', value }] : [];

package/dist/parse-description.d.ts

@@ -3,4 +3,6 @@ import type { RootContent } from 'mdast';
 export type DescriptionParser = (value?: string) => Promise<RootContent[]>;
 /** Share parsing across pages while giving every rendered document its own reference namespace. */
 export declare const createDescriptionParser: () => (() => DescriptionParser);
+/** Replace every deferred description in the given nodes with its parsed Markdown blocks. */
+export declare const expandDescriptions: (nodes: RootContent[], description: DescriptionParser) => Promise<void>;
 //# sourceMappingURL=parse-description.d.ts.map

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,EAAe,WAAW,EAAE,MAAM,OAAO,CAAA;AA2ErD,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,CA0ClE,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;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"}

package/dist/parse-description.js

@@ -68,10 +68,18 @@ const pruneDefinitions = (tree) => {
         return true;
     });
 };
+/**
+ * A single line without Markdown punctuation, entities, autolinks or block markers parses to one
+ * paragraph containing the same text, so it does not need the parser.
+ */
+const isPlainText = (value) => !/[\n\r\t\\`*_[\]<>#|~!&=]|:\/\/|www\.|^\s*(?:[-+]|\d+[.)])|^ {4}/.test(value) && value.trim().length > 0;
 /** Share parsing across pages while giving every rendered document its own reference namespace. */
 export const createDescriptionParser = () => {
     const cache = new Map();
     const parse = async (value) => {
+        // Most schema descriptions are one plain sentence. Parsing them costs more than the page's other text.
+        if (isPlainText(value))
+            return [{ type: 'paragraph', children: [{ type: 'text', value: value.trim() }] }];
         const parsed = parser.parse(value);
         // Raw HTML and GitHub alerts retain Scalar's existing conversion behavior.
         const tree = containsHtml(parsed) || /^\s*>\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION|SUCCESS)\]/im.test(value)
@@ -103,7 +111,7 @@ export const createDescriptionParser = () => {
             const prefix = `description-${state.nextId++}-`;
             const cached = cache.get(value) ?? parse(value);
             if (!cache.has(value)) {
-                if (cache.size >= 256)
+                if (cache.size >= 8192)
                     cache.clear();
                 cache.set(value, cached);
             }
@@ -114,3 +122,22 @@ export const createDescriptionParser = () => {
         };
     };
 };
+/** Replace every deferred description in the given nodes with its parsed Markdown blocks. */
+export const expandDescriptions = async (nodes, description) => {
+    const found = [];
+    const collect = (siblings) => {
+        for (const node of siblings) {
+            if (node.type === 'descriptionPlaceholder')
+                found.push({ siblings, node });
+            else if ('children' in node)
+                collect(node.children);
+        }
+    };
+    collect(nodes);
+    const parsed = await Promise.all(found.map(({ node }) => description(node.value)));
+    // Replace from the end, so earlier positions in a shared sibling list stay valid.
+    for (let index = found.length - 1; index >= 0; index--) {
+        const { siblings, node } = found[index];
+        siblings.splice(siblings.indexOf(node), 1, ...parsed[index]);
+    }
+};

package/dist/render-document.d.ts

@@ -1,5 +1,5 @@
 import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
-import type { SchemaReferenceOptions } from './select-document.js';
+import type { OpenApiRenderOptions } from './select-document.js';
 /** Build Markdown directly, retaining caches only for this immutable document snapshot. */
-export declare const createDocumentRenderer: () => ((document: OpenApiDocument, options?: SchemaReferenceOptions) => Promise<string>);
+export declare const createDocumentRenderer: () => ((document: OpenApiDocument, options?: OpenApiRenderOptions) => 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;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"}
+{"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;AA+C7D,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,MAAM,CAAC,CAsPnB,CAAA"}