@scalar/openapi-to-markdown 0.5.44 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @scalar/openapi-to-markdown
 
+## 1.0.0
+
+### Major Changes
+
+- [#10233](https://github.com/scalar/scalar/pull/10233): Generate Markdown directly from a Markdown syntax tree, avoiding Vue server rendering and the generated HTML conversion pipeline. Reuse normalized schemas and parsed descriptions across pages while preserving selection, schema coercion, reference resolution, and raw HTML description sanitization.
+
+  Keep the HTML API through an on-demand Markdown conversion. Markdown and HTML spacing and escaping may differ from previous output.
+
+### Minor Changes
+
+- [#10224](https://github.com/scalar/scalar/pull/10224): Add a reusable renderer that loads an OpenAPI document once and generates multiple Markdown or HTML pages from it.
+
+### Patch Changes
+
+- [#10241](https://github.com/scalar/scalar/pull/10241): Simplify reference link rebuilding after OpenAPI document coercion.
+
+## 0.6.0
+
+### Minor Changes
+
+- [#10169](https://github.com/scalar/scalar/pull/10169): Render scoped operation, tag, model, webhook, and introduction pages in Markdown and HTML while preserving referenced schemas and inherited context.
+
 ## 0.5.44
 
 ## 0.5.43

package/README.md

@@ -68,13 +68,42 @@ const operationMarkdownByPointer = await createMarkdownFromOpenApi(content, {
 })
 ```
 
+### Render multiple pages
+
+Create a reusable renderer when exporting several pages from the same API description.
+It loads, upgrades, coerces, and resolves the document once. Each call uses the same selectors as
+`createMarkdownFromOpenApi`, and omitting a selector renders the complete document.
+
+```ts
+import { createOpenApiMarkdownRenderer } from '@scalar/openapi-to-markdown'
+
+const renderer = await createOpenApiMarkdownRenderer(content)
+
+const introduction = await renderer.render({ introduction: true })
+const operation = await renderer.render({
+  operation: { path: '/users/{id}', method: 'get' },
+})
+const tag = await renderer.render({ tag: 'Users' })
+const model = await renderer.render({ model: 'User' })
+const webhook = await renderer.render({
+  webhook: { name: 'userCreated', method: 'post' },
+})
+```
+
+The factory accepts the same document objects, JSON/YAML strings, file paths, and URLs
+as the one-shot functions. Source files and URLs are read during creation, including
+references. Create a new renderer when the source changes. Reuse one renderer per API
+description during a build, then release it when the build finishes. Renderers do not
+share a global document cache. An invalid selection rejects that call without preventing
+later calls on the same renderer.
+
 ### With Hono
 
 You use the package with any Node.js framework. Here is an example for [Hono](https://hono.dev/):
 
 ```ts
-import { Hono } from 'hono'
 import { createMarkdownFromOpenApi } from '@scalar/openapi-to-markdown'
+import { Hono } from 'hono'
 
 // Generate Markdown from an OpenAPI document
 const markdown = await createMarkdownFromOpenApi(content)
@@ -94,43 +123,21 @@ app.get('/llms.txt', (c) => c.text(markdown))
 serve(app)
 ```
 
-### Generate HTML
-
-This is not really the purpose of the package, but maybe good to know: This package actually renders HTML at first, and
-transforms the HTML to Markdown then.
+### Markdown rendering
 
-So if you'd like to have a really light-weight HTML API Reference, here you are:
+The renderer constructs a Markdown syntax tree directly from the resolved API description.
+It preserves Markdown descriptions, GFM tables and code blocks without rendering a Vue app
+or converting the generated document through HTML. Descriptions containing raw HTML or
+Scalar alerts use a separate sanitization and conversion path. Images remain excluded.
 
-```ts
-import { Hono } from 'hono'
-import { createHtmlFromOpenApi } from '@scalar/openapi-to-markdown'
+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.
 
-// Generate HTML from an OpenAPI document
-const html = await createHtmlFromOpenApi(content)
-
-const app = new Hono()
+### HTML output
 
-app.get('/', (c) =>
-  c.html(
-    `<!doctype html>
-<html lang="en" data-theme="light">
-<head>
-  <meta charset="UTF-8" />
-  <title>Scalar Galaxy</title>
-  <!-- Basic styling for semantic HTML tags (optional) -->
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
-</head>
-<body>
-  <main class="container">
-    ${html}
-  </main>
-</body>
-</html>`,
-  ),
-)
-
-serve(app)
-```
+`createHtmlFromOpenApi` and `renderer.renderHtml` remain available. They convert the
+Markdown output to HTML on demand, without loading a Vue renderer.
 
 ## Community
 
@@ -139,3 +146,35 @@ We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>
 ## License
 
 The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).
+
+## Individual reference pages
+
+`createMarkdownFromOpenApi` and `renderer.render` accept the same selection options. Choose one selector per call:
+
+```ts
+await createMarkdownFromOpenApi(content, { tag: 'pets' })
+await createMarkdownFromOpenApi(content, { model: 'Pet' })
+await createMarkdownFromOpenApi(content, {
+  webhook: { name: 'petCreated', method: 'post' },
+})
+await createMarkdownFromOpenApi(content, { introduction: true })
+await createMarkdownFromOpenApi(content, {
+  operation: { operationId: 'getUser' },
+})
+```
+
+- **Operation:** One operation, effective parameters, servers and authentication, its tags, and referenced component schemas. Existing path/method, operation ID, and JSON pointer selectors still work. Methods are case insensitive.
+- **Tag:** Tag metadata and all path operations with that exact tag, plus their context and schema dependencies. A tag used only by operations is supported. A declared tag with no operations renders its metadata. Operations with multiple tags appear once, with only the selected tag shown.
+- **Model:** One component schema and its referenced schemas. Primitive, array, composed, and recursive models use the shared schema renderer.
+- **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.
+
+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.
+
+### 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.

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

@@ -1,18 +1,19 @@
-import type { HttpMethod } from '@scalar/helpers/http/http-methods';
-import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.1/strict/openapi-document';
+import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import { type OpenApiRenderOptions } from './select-document.js';
 type AnyDocument = OpenApiDocument | Record<string, unknown> | string;
-export type { HttpMethod };
-export type OperationSelector = {
-    path: string;
-    method: HttpMethod | Uppercase<HttpMethod>;
-} | {
-    operationId: string;
-} | {
-    pointer: string;
+/** A resolved API description that can render multiple pages without loading it again. */
+export type OpenApiMarkdownRenderer = {
+    render: (options?: OpenApiRenderOptions) => Promise<string>;
+    renderHtml: (options?: OpenApiRenderOptions) => Promise<string>;
 };
-export type OpenApiRenderOptions = {
-    operation?: OperationSelector;
-};
-export declare function createHtmlFromOpenApi(input: AnyDocument, options?: OpenApiRenderOptions): Promise<string>;
-export declare function createMarkdownFromOpenApi(content: AnyDocument, options?: OpenApiRenderOptions): Promise<string>;
+/**
+ * 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>;
+/** Generate Markdown from an API description, optionally scoped to a single page. */
+export declare const createMarkdownFromOpenApi: (input: AnyDocument, options?: OpenApiRenderOptions) => Promise<string>;
+/** Generate HTML through the optional Markdown conversion path. */
+export declare const createHtmlFromOpenApi: (input: AnyDocument, options?: OpenApiRenderOptions) => Promise<string>;
+export {};
 //# sourceMappingURL=create-markdown-from-openapi.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAMnE,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAanH,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,YAAY,EAAE,UAAU,EAAE,CAAA;AAC1B,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;CAC3C,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,CAAC,EAAE,iBAAiB,CAAA;CAC9B,CAAA;AAwMD,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,oBAAoB,mBA8C7F;AAED,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,oBAAoB,mBAEnG"}
+{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAInG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3D,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAChE,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GAAU,OAAO,WAAW,KAAG,OAAO,CAAC,uBAAuB,CAoBvG,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAGhB,CAAA;AAED,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,GAAU,OAAO,WAAW,EAAE,UAAU,oBAAoB,KAAG,OAAO,CAAC,MAAM,CAG9G,CAAA"}

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

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

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,gCAAgC,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,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}