@scalar/openapi-to-markdown 0.6.0 → 1.0.0

package/CHANGELOG.md

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

package/README.md

@@ -68,6 +68,35 @@ 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/):
@@ -94,43 +123,21 @@ app.get('/llms.txt', (c) => c.text(markdown))
 serve(app)
 ```
 
-### Generate HTML
+### Markdown rendering
 
-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.
+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.
 
-So if you'd like to have a really light-weight HTML API Reference, here you are:
+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.
 
-```ts
-import { createHtmlFromOpenApi } from '@scalar/openapi-to-markdown'
-import { Hono } from 'hono'
-
-// 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
 
@@ -142,7 +149,7 @@ The source code in this repository is licensed under [MIT](https://github.com/sc
 
 ## Individual reference pages
 
-Both `createMarkdownFromOpenApi` and `createHtmlFromOpenApi` accept the same options. Choose one selector per call:
+`createMarkdownFromOpenApi` and `renderer.render` accept the same selection options. Choose one selector per call:
 
 ```ts
 await createMarkdownFromOpenApi(content, { tag: 'pets' })
@@ -151,7 +158,9 @@ await createMarkdownFromOpenApi(content, {
   webhook: { name: 'petCreated', method: 'post' },
 })
 await createMarkdownFromOpenApi(content, { introduction: true })
-await createHtmlFromOpenApi(content, { operation: { operationId: 'getUser' } })
+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.

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

@@ -1,29 +1,19 @@
-import type { HttpMethod } from '@scalar/helpers/http/http-methods';
 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>;
 };
-/** Select one reference page, or omit selectors for the whole document. */
-export type OpenApiRenderOptions = {
-    [Key in keyof PageSelectors]: Partial<Record<Exclude<keyof PageSelectors, Key>, never>> & Pick<PageSelectors, Key>;
-}[keyof PageSelectors] | Partial<Record<keyof PageSelectors, never>>;
-type PageSelectors = {
-    operation: OperationSelector;
-    tag: string;
-    model: string;
-    webhook: {
-        name: string;
-        method: HttpMethod | Uppercase<HttpMethod>;
-    };
-    introduction: true;
-};
-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;AAOnE,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,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAC5B;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CACnH,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAAA;AAE/C,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAA;KAAE,CAAA;IACrE,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AA6ZD,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,oBAAoB,mBA2C7F;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"}