@scalar/hono-api-reference 0.8.9 → 0.9.1

package/README.md

@@ -28,6 +28,14 @@ const app = new Hono()
 // Use the middleware to serve the Scalar API Reference at /scalar
 app.get('/scalar', Scalar({ url: '/doc' }))
 
+// Or with dynamic configuration
+app.get('/scalar', Scalar((c) => {
+  return {
+    url: '/doc',
+    proxyUrl: c.env.ENVIRONMENT === 'development' ? 'https://proxy.scalar.com' : undefined,
+  }
+}))
+
 export default app
 ```
 
@@ -63,7 +71,7 @@ app.get('/scalar', Scalar({
 
 ### Custom CDN
 
-You can use a custom CDN ，default is `https://cdn.jsdelivr.net/npm/@scalar/api-reference`.
+You can use a custom CDN, default is `https://cdn.jsdelivr.net/npm/@scalar/api-reference`.
 
 You can also pin the CDN to a specific version by specifying it in the CDN string like `https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28`
 
@@ -80,6 +88,54 @@ app.get('/scalar', Scalar({
 }))
 ```
 
+### Markdown for LLMs
+
+If you want to create a Markdown version of the API reference (for LLMs), install `@scalar/openapi-to-markdown`:
+
+```bash
+npm install @scalar/openapi-to-markdown
+```
+
+And add an additional route for it:
+
+```ts
+import { Hono } from 'hono'
+import { createMarkdownFromOpenApi } from '@scalar/openapi-to-markdown'
+
+const app = new Hono()
+
+// Generate Markdown from your OpenAPI document
+const markdown = await createMarkdownFromOpenApi(content)
+
+/**
+ * Register a route to serve the Markdown for LLMs
+ *
+ * Q: Why /llms.txt?
+ * A: It's a proposal to standardise on using an /llms.txt file.
+ *
+ * @see https://llmstxt.org/
+ */
+app.get('/llms.txt', (c) => c.text(markdown))
+
+export default app
+```
+
+Or, if you are using Zod OpenAPI Hono:
+
+```ts
+// Get the OpenAPI document
+const content = app.getOpenAPI31Document({
+  openapi: '3.1.0',
+  info: { title: 'Example', version: 'v1' },
+})
+
+const markdown = await createMarkdownFromOpenApi(JSON.stringify(content))
+
+app.get('/llms.txt', async (c) => {
+  return c.text(markdown)
+})
+```
+
 ## Community
 
 We are API nerds. You too? Let’s chat on Discord: <https://discord.gg/scalar>

package/dist/scalar.d.ts

@@ -1,15 +1,17 @@
-import type { Env, MiddlewareHandler } from 'hono';
+import type { Context, Env, MiddlewareHandler } from 'hono';
 import type { ApiReferenceConfiguration } from './types';
 /**
  * The custom theme for Hono
  */
 export declare const customTheme = "\n.light-mode {\n  color-scheme: light;\n  --scalar-color-1: #2a2f45;\n  --scalar-color-2: #757575;\n  --scalar-color-3: #8e8e8e;\n  --scalar-color-disabled: #b4b1b1;\n  --scalar-color-ghost: #a7a7a7;\n  --scalar-color-accent: #0099ff;\n  --scalar-background-1: #fff;\n  --scalar-background-2: #f6f6f6;\n  --scalar-background-3: #e7e7e7;\n  --scalar-background-4: rgba(0, 0, 0, 0.06);\n  --scalar-background-accent: #8ab4f81f;\n\n  --scalar-border-color: rgba(0, 0, 0, 0.1);\n  --scalar-scrollbar-color: rgba(0, 0, 0, 0.18);\n  --scalar-scrollbar-color-active: rgba(0, 0, 0, 0.36);\n  --scalar-lifted-brightness: 1;\n  --scalar-backdrop-brightness: 1;\n\n  --scalar-shadow-1: 0 1px 3px 0 rgba(0, 0, 0, 0.11);\n  --scalar-shadow-2: rgba(0, 0, 0, 0.08) 0px 13px 20px 0px,\n    rgba(0, 0, 0, 0.08) 0px 3px 8px 0px, #eeeeed 0px 0 0 1px;\n\n  --scalar-button-1: rgb(49 53 56);\n  --scalar-button-1-color: #fff;\n  --scalar-button-1-hover: rgb(28 31 33);\n\n  --scalar-color-green: #069061;\n  --scalar-color-red: #ef0006;\n  --scalar-color-yellow: #edbe20;\n  --scalar-color-blue: #0082d0;\n  --scalar-color-orange: #fb892c;\n  --scalar-color-purple: #5203d1;\n}\n\n.dark-mode {\n  color-scheme: dark;\n  --scalar-color-1: rgba(255, 255, 245, .86);\n  --scalar-color-2: rgba(255, 255, 245, .6);\n  --scalar-color-3: rgba(255, 255, 245, .38);\n  --scalar-color-disabled: rgba(255, 255, 245, .25);\n  --scalar-color-ghost: rgba(255, 255, 245, .25);\n  --scalar-color-accent: #e36002;\n  --scalar-background-1: #1e1e20;\n  --scalar-background-2: #2a2a2a;\n  --scalar-background-3: #505053;\n  --scalar-background-4: rgba(255, 255, 255, 0.06);\n  --scalar-background-accent: #e360021f;\n\n  --scalar-border-color: rgba(255, 255, 255, 0.1);\n  --scalar-scrollbar-color: rgba(255, 255, 255, 0.24);\n  --scalar-scrollbar-color-active: rgba(255, 255, 255, 0.48);\n  --scalar-lifted-brightness: 1.45;\n  --scalar-backdrop-brightness: 0.5;\n\n  --scalar-shadow-1: 0 1px 3px 0 rgb(0, 0, 0, 0.1);\n  --scalar-shadow-2: rgba(15, 15, 15, 0.2) 0px 3px 6px,\n    rgba(15, 15, 15, 0.4) 0px 9px 24px, 0 0 0 1px rgba(255, 255, 255, 0.1);\n\n  --scalar-button-1: #f6f6f6;\n  --scalar-button-1-color: #000;\n  --scalar-button-1-hover: #e7e7e7;\n\n  --scalar-color-green: #3dd68c;\n  --scalar-color-red: #f66f81;\n  --scalar-color-yellow: #f9b44e;\n  --scalar-color-blue: #5c73e7;\n  --scalar-color-orange: #ff8d4d;\n  --scalar-color-purple: #b191f9;\n}\n/* Sidebar */\n.light-mode .t-doc__sidebar {\n  --scalar-sidebar-background-1: var(--scalar-background-1);\n  --scalar-sidebar-item-hover-color: currentColor;\n  --scalar-sidebar-item-hover-background: var(--scalar-background-2);\n  --scalar-sidebar-item-active-background: var(--scalar-background-accent);\n  --scalar-sidebar-border-color: var(--scalar-border-color);\n  --scalar-sidebar-color-1: var(--scalar-color-1);\n  --scalar-sidebar-color-2: var(--scalar-color-2);\n  --scalar-sidebar-color-active: var(--scalar-color-accent);\n  --scalar-sidebar-search-background: var(--scalar-background-2);\n  --scalar-sidebar-search-border-color: var(--scalar-sidebar-border-color);\n  --scalar-sidebar-search-color: var(--scalar-color-3);\n}\n\n.dark-mode .sidebar {\n  --scalar-sidebar-background-1: #161618;\n  --scalar-sidebar-item-hover-color: var(--scalar-color-accent);\n  --scalar-sidebar-item-hover-background: transparent;\n  --scalar-sidebar-item-active-background: transparent;\n  --scalar-sidebar-border-color: transparent;\n  --scalar-sidebar-color-1: var(--scalar-color-1);\n  --scalar-sidebar-color-2: var(--scalar-color-2);\n  --scalar-sidebar-color-active: var(--scalar-color-accent);\n  --scalar-sidebar-search-background: #252529;\n  --scalar-sidebar-search-border-color: transparent;\n  --scalar-sidebar-search-color: var(--scalar-color-3);\n}\n";
+type Configuration<E extends Env> = Partial<ApiReferenceConfiguration> | ((c: Context<E>) => Partial<ApiReferenceConfiguration> | Promise<Partial<ApiReferenceConfiguration>>);
 /**
  * The Hono middleware for the Scalar API Reference.
  */
-export declare const Scalar: <E extends Env>(givenConfiguration: Partial<ApiReferenceConfiguration>) => MiddlewareHandler<E>;
+export declare const Scalar: <E extends Env>(configOrResolver: Configuration<E>) => MiddlewareHandler<E>;
 /**
  * @deprecated Use `Scalar` instead.
  */
-export declare const apiReference: <E extends Env>(givenConfiguration: Partial<ApiReferenceConfiguration>) => MiddlewareHandler<E>;
+export declare const apiReference: <E extends Env>(configOrResolver: Configuration<E>) => MiddlewareHandler<E>;
+export {};
 //# sourceMappingURL=scalar.d.ts.map

package/dist/scalar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../src/scalar.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAElD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AASxD;;GAEG;AACH,eAAO,MAAM,WAAW,mtHAoGvB,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,GAAG,sBAAsB,OAAO,CAAC,yBAAyB,CAAC,KAAG,iBAAiB,CAAC,CAAC,CASjH,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,GAdF,CAAC,SAAS,GAAG,sBAAsB,OAAO,CAAC,yBAAyB,CAAC,KAAG,iBAAiB,CAAC,CAAC,CAchF,CAAA"}
+{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../src/scalar.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AASxD;;GAEG;AACH,eAAO,MAAM,WAAW,mtHAoGvB,CAAA;AAED,KAAK,aAAa,CAAC,CAAC,SAAS,GAAG,IAC5B,OAAO,CAAC,yBAAyB,CAAC,GAClC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,yBAAyB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAA;AAEzG;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,GAAG,oBAAoB,aAAa,CAAC,CAAC,CAAC,KAAG,iBAAiB,CAAC,CAAC,CAmB7F,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,GAxBF,CAAC,SAAS,GAAG,oBAAoB,aAAa,CAAC,CAAC,CAAC,KAAG,iBAAiB,CAAC,CAAC,CAwB5D,CAAA"}

package/dist/scalar.js

@@ -113,14 +113,23 @@ const customTheme = `
 /**
  * The Hono middleware for the Scalar API Reference.
  */
-const Scalar = (givenConfiguration) => {
-    // Merge the defaults
-    const configuration = {
-        ...DEFAULT_CONFIGURATION,
-        ...givenConfiguration,
+const Scalar = (configOrResolver) => {
+    return async (c) => {
+        let resolvedConfig = {};
+        if (typeof configOrResolver === 'function') {
+            resolvedConfig = await configOrResolver(c);
+        }
+        else {
+            resolvedConfig = configOrResolver;
+        }
+        // Merge the defaults
+        const configuration = {
+            ...DEFAULT_CONFIGURATION,
+            ...resolvedConfig,
+        };
+        // Respond with the HTML document
+        return c.html(getHtmlDocument(configuration, customTheme));
     };
-    // Respond with the HTML document
-    return async (c) => c.html(/* html */ `${getHtmlDocument(configuration, customTheme)}`);
 };
 /**
  * @deprecated Use `Scalar` instead.

package/package.json

@@ -10,9 +10,9 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "integrations/hono"
   },
-  "version": "0.8.9",
+  "version": "0.9.1",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
   ],
   "module": "dist/index.js",
   "dependencies": {
-    "@scalar/core": "0.2.15"
+    "@scalar/core": "0.3.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.11.0",
@@ -37,7 +37,8 @@
     "hono": "^4.6.5",
     "vite": "5.4.19",
     "vitest": "^1.6.0",
-    "@scalar/build-tooling": "0.1.19"
+    "@scalar/openapi-to-markdown": "0.2.1",
+    "@scalar/build-tooling": "0.2.0"
   },
   "peerDependencies": {
     "hono": "^4.0.0"