@stainless-api/docs 0.1.0-beta.0

package/plugin/vendor/templates/typescript.md

@@ -0,0 +1,317 @@
+# SDK_PackageTitle API Library
+
+[![NPM version](https://img.shields.io/npm/v/SDK_NPMPackage.svg?label=npm%20(stable))](https://npmjs.org/package/SDK_NPMPackage) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/SDK_NPMPackage)SDK_JSRShield
+
+SDK_ReadmeOpening
+
+SDK_ScreencastURL
+
+SDK_DocumentationReference
+
+SDK_GeneratedByStainless
+
+## Installation
+
+SDK_NPMInstallInstructions
+
+SDK_JSRInstallation
+
+## Usage
+
+SDK_APIReference
+
+<!-- prettier-ignore -->
+```js
+SDK_Usage
+```
+
+SDK_StreamingUsage
+
+### Request & Response types
+
+This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
+
+<!-- prettier-ignore -->
+```ts
+SDK_TypeScriptUsage
+```
+
+Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
+
+SDK_FileUploadsUsage
+
+SDK_BinaryUploadsUsage
+
+## Handling errors
+
+When the library is unable to connect to the API,
+or if the API returns a non-success status code (i.e., 4xx or 5xx response),
+a subclass of `APIError` will be thrown:
+
+<!-- prettier-ignore -->
+```ts
+SDK_ErrorsExample
+```
+
+Error codes are as follows:
+
+| Status Code | Error Type                 |
+| ----------- | -------------------------- |
+| 400         | `BadRequestError`          |
+| 401         | `AuthenticationError`      |
+| 403         | `PermissionDeniedError`    |
+| 404         | `NotFoundError`            |
+| 422         | `UnprocessableEntityError` |
+| 429         | `RateLimitError`           |
+| >=500       | `InternalServerError`      |
+| N/A         | `APIConnectionError`       |
+
+### Retries
+
+Certain errors will be automatically retried SDK_DefaultMaxRetries times by default, with a short exponential backoff.
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
+429 Rate Limit, and >=500 Internal errors will all be retried by default.
+
+You can use the `maxRetries` option to configure or disable this:
+
+<!-- prettier-ignore -->
+```js
+SDK_RetriesExample
+```
+
+### Timeouts
+
+Requests time out after SDK_HumanReadableDefaultTimeout by default. You can configure this with a `timeout` option:
+
+<!-- prettier-ignore -->
+```ts
+SDK_TimeoutsExample
+```
+
+On timeout, an `APIConnectionTimeoutError` is thrown.
+
+Note that requests which time out will be [retried twice by default](#retries).
+
+SDK_Pagination
+
+SDK_DefaultHeaders
+
+## Advanced Usage
+SDK_TreeShakingDocs
+### Accessing raw Response data (e.g., headers)
+
+The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
+This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
+
+You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
+Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
+
+<!-- prettier-ignore -->
+```ts
+SDK_RawResponseExample
+```
+
+### Logging
+
+> [!IMPORTANT]
+> All log messages are intended for debugging only. The format and content of log messages
+> may change between releases.
+
+#### Log levels
+
+The log level can be configured in two ways:
+
+1. Via the `SDK_PackageLoggingEnvVar` environment variable
+2. Using the `logLevel` client option (overrides the environment variable if set)
+
+```ts
+import SDK_PackageName from 'SDK_NPMPackage';
+
+const SDK_ClientName = new SDK_PackageName({
+  logLevel: 'debug', // Show all log messages
+});
+```
+
+Available log levels, from most to least verbose:
+
+- `'debug'` - Show debug messages, info, warnings, and errors
+- `'info'` - Show info messages, warnings, and errors
+- `'warn'` - Show warnings and errors (default)
+- `'error'` - Show only errors
+- `'off'` - Disable all logging
+
+At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
+Some authentication-related headers are redacted, but sensitive data in request and response bodies
+may still be visible.
+
+#### Custom logger
+
+By default, this library logs to `globalThis.console`. You can also provide a custom logger.
+Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
+
+When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
+below the configured level will not be sent to your logger.
+
+```ts
+import SDK_PackageName from 'SDK_NPMPackage';
+import pino from 'pino';
+
+const logger = pino();
+
+const SDK_ClientName = new SDK_PackageName({
+  logger: logger.child({ name: 'SDK_PackageName' }),
+  logLevel: 'debug', // Send all messages to pino, allowing it to filter
+});
+```
+
+### Making custom/undocumented requests
+
+This library is typed for convenient access to the documented API. If you need to access undocumented
+endpoints, params, or response properties, the library can still be used.
+
+#### Undocumented endpoints
+
+To make requests to undocumented endpoints, you can use `SDK_ClientName.get`, `SDK_ClientName.post`, and other HTTP verbs.
+Options on the client, such as retries, will be respected when making these requests.
+
+```ts
+await SDK_ClientName.post('/some/path', {
+  body: { some_prop: 'foo' },
+  query: { some_query_arg: 'bar' },
+});
+```
+
+#### Undocumented request params
+
+To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
+parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
+send will be sent as-is.
+
+```ts
+SDK_ExampleClientMethodName({
+  // ...
+  // @ts-expect-error baz is not yet public
+  baz: 'undocumented option',
+});
+```
+
+For requests with the `GET` verb, any extra params will be in the query, all other requests will send the
+extra param in the body.
+
+If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
+options.
+
+#### Undocumented response properties
+
+To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
+the response object, or cast the response object to the requisite type. Like the request params, we do not
+validate or strip extra properties from the response from the API.
+
+### Customizing the fetch client
+
+By default, this library expects a global `fetch` function is defined.
+
+If you want to use a different `fetch` function, you can either polyfill the global:
+
+```ts
+import fetch from 'my-fetch';
+
+globalThis.fetch = fetch;
+```
+
+Or pass it to the client:
+
+```ts
+import SDK_PackageName from 'SDK_NPMPackage';
+import fetch from 'my-fetch';
+
+const SDK_ClientName = new SDK_PackageName({ fetch });
+```
+
+### Fetch options
+
+If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
+
+```ts
+import SDK_PackageName from 'SDK_NPMPackage';
+
+const SDK_ClientName = new SDK_PackageName({
+  fetchOptions: {
+    // `RequestInit` options
+  },
+});
+```
+
+#### Configuring proxies
+
+To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
+options to requests:
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
+
+```ts
+import SDK_PackageName from 'SDK_NPMPackage';
+import * as undici from 'undici';
+
+const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
+const SDK_ClientName = new SDK_PackageName({
+  fetchOptions: {
+    dispatcher: proxyAgent,
+  },
+});
+```
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
+
+```ts
+import SDK_PackageName from 'SDK_NPMPackage';
+
+const SDK_ClientName = new SDK_PackageName({
+  fetchOptions: {
+    proxy: 'http://localhost:8888',
+  },
+});
+```
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+
+```ts
+import SDK_PackageName from 'SDK_DenoSpecifier';
+
+const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
+const SDK_ClientName = new SDK_PackageName({
+  fetchOptions: {
+    client: httpClient,
+  },
+});
+```
+
+## Frequently Asked Questions
+
+## Semantic versioning
+
+This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
+
+1. Changes that only affect static types, without breaking runtime behavior.
+2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
+3. Changes that we do not expect to impact the vast majority of users in practice.
+
+We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
+
+We are keen for your feedback; please open an [issue](SDK_GitHubRepoURL/issues) with questions, bugs, or suggestions.
+
+## Requirements
+
+TypeScript >= 4.9 is supported.
+
+The following runtimes are supported:
+
+SDK_SupportedRuntimes
+
+Note that React Native is not supported at this time.
+
+If you are interested in other runtime environments, please open or upvote an issue on GitHub.
+
+## Contributing
+
+See [the contributing documentation](./CONTRIBUTING.md).

package/scripts/vendor_deps.ts

@@ -0,0 +1,50 @@
+import { config } from 'dotenv';
+import fs from 'fs';
+import path from 'path';
+import { z } from 'zod';
+
+import { Languages } from '@stainless-api/docs-ui/src/routing';
+
+const DEPS_DIR = './plugin/vendor';
+
+config();
+
+const envSchema = z.object({
+  // absolute path to the Stainless monorepo root
+  STAINLESS_MONOREPO_PATH: z.string(),
+});
+
+const env = envSchema.parse(process.env);
+
+console.log(`Using Stainless monorepo at ${env.STAINLESS_MONOREPO_PATH}`);
+
+if (fs.existsSync(DEPS_DIR)) {
+  fs.rmSync(DEPS_DIR, { recursive: true });
+}
+
+fs.mkdirSync(DEPS_DIR, { recursive: true });
+
+const previewWorkerPath = path.join(
+  env.STAINLESS_MONOREPO_PATH,
+  '/packages/preview-worker/dist/stainless/preview.worker.docs.js',
+);
+
+const readmeTemplatePath = path.join(env.STAINLESS_MONOREPO_PATH, '/legacy-dir-root/templates');
+
+fs.copyFileSync(previewWorkerPath, path.join(DEPS_DIR, 'preview.worker.docs.js'));
+
+console.log(`✅ cp ${previewWorkerPath} -> ${path.join(DEPS_DIR, 'preview.worker.docs.js')}`);
+
+if (fs.existsSync(readmeTemplatePath)) {
+  fs.mkdirSync(path.join(DEPS_DIR, 'templates'));
+
+  for (const language of Languages) {
+    const mdPath = path.join(readmeTemplatePath, language, 'README.md');
+    const dest = path.join(DEPS_DIR, 'templates', `${language}.md`);
+
+    if (fs.existsSync(mdPath)) {
+      fs.copyFileSync(mdPath, dest);
+      console.log(`✅ cp ${mdPath} -> ${dest}`);
+    }
+  }
+}

package/shared/virtualModule.ts

@@ -0,0 +1,7 @@
+export function buildVirtualModuleString(vars: Record<string, any>) {
+  return Object.entries(vars)
+    .map(([key, value]) => {
+      return `export const ${key} = ${JSON.stringify(value)};`;
+    })
+    .join('\n');
+}

package/stl-docs/components/APIReferenceAIDropdown.tsx

@@ -0,0 +1,86 @@
+import {
+  DropdownButton,
+  DropdownButtonDivider,
+  DropdownButtonItem,
+  DropdownButtonItemIcon,
+  DropdownButtonItemText,
+  DropdownButtonItemTextSubtle,
+  DropdownButtonMenu,
+  DropdownButtonPrimaryAction,
+  DropdownButtonPrimaryActionText,
+  DropdownButtonTrigger,
+} from '@stainless-api/ui-primitives';
+import { CopyIcon } from 'lucide-react';
+
+export function AIDropdownOptions() {
+  return (
+    <>
+      <DropdownButtonItem value="chat-gpt" isExternalLink>
+        <DropdownButtonItemIcon>
+          <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none">
+            <path
+              d="M3.13924 10.6036L6.28658 8.84444L6.33924 8.69111L6.28658 8.60638H6.13266L5.60608 8.5741L3.8076 8.52568L2.2481 8.46113L0.737215 8.38043L0.356456 8.29973L0 7.83169L0.0364557 7.59766L0.356456 7.38382L0.814177 7.42416L1.82684 7.49276L3.34582 7.59766L4.4476 7.66222L6.08 7.83169H6.33924L6.3757 7.72678L6.28658 7.66222L6.21772 7.59766L4.64608 6.53649L2.94481 5.4148L2.05367 4.76922L1.57165 4.44239L1.32861 4.13574L1.22329 3.46595L1.66076 2.98581L2.2481 3.02615L2.39797 3.0665L2.99342 3.52244L4.26532 4.50292L5.92608 5.72145L6.16911 5.92319L6.26633 5.8546L6.27848 5.80618L6.16911 5.62461L5.26582 3.99856L4.30177 2.34426L3.87241 1.65833L3.75899 1.24678C3.71848 1.07731 3.69013 0.93609 3.69013 0.762591L4.18835 0.0887672L4.4638 0L5.1281 0.0887672L5.4076 0.330859L5.82076 1.27098L6.48911 2.75178L7.52608 4.76518L7.82987 5.36234L7.9919 5.91512L8.05266 6.08459H8.15797V5.98775L8.24304 4.85395L8.40101 3.46192L8.55494 1.67044L8.60759 1.16608L8.85873 0.560847L9.35696 0.234023L9.74582 0.419627L10.0658 0.875567L10.0213 1.17011L9.83089 2.40075L9.45823 4.32942L9.21519 5.62058H9.35696L9.51899 5.45918L10.1752 4.59168L11.277 3.21983L11.763 2.67512L12.3301 2.07392L12.6947 1.78745H13.3833L13.8896 2.53793L13.6628 3.31263L12.9539 4.20837L12.3666 4.96693L11.5241 6.09669L10.9975 7.0005L11.0461 7.07313L11.1716 7.06103L13.0754 6.65754L14.1043 6.47193L15.3316 6.26212L15.8866 6.52035L15.9473 6.78262L15.7286 7.31926L14.4162 7.64205L12.877 7.9487L10.5843 8.48937L10.5559 8.50954L10.5884 8.54989L11.6213 8.64673L12.0628 8.67094H13.1443L15.1575 8.82023L15.6841 9.16723L16 9.59089L15.9473 9.91368L15.1372 10.3252L14.0435 10.067L11.4916 9.46177L10.6167 9.24389H10.4952V9.31652L11.2243 10.0267L12.561 11.229L14.2339 12.7784L14.319 13.1618L14.1043 13.4644L13.8775 13.4321L12.4071 12.3306L11.84 11.8343L10.5559 10.757H10.4709V10.8699L10.7666 11.3017L12.3301 13.6419L12.4111 14.3601L12.2977 14.5941L11.8927 14.7354L11.4471 14.6547L10.5316 13.3756L9.58785 11.9352L8.82633 10.644L8.73316 10.6964L8.28354 15.5181L8.07291 15.7642L7.58684 15.9498L7.18177 15.6432L6.96709 15.1469L7.18177 14.1664L7.44101 12.8874L7.65165 11.8706L7.84203 10.6077L7.95544 10.1881L7.94734 10.1598L7.85418 10.1719L6.89823 11.4792L5.44405 13.4361L4.29367 14.6627L4.01823 14.7717L3.54025 14.5255L3.58481 14.0857L3.85215 13.6944L5.44405 11.6769L6.40405 10.4261L7.0238 9.70387L7.01975 9.59896H6.98329L2.75443 12.3346L2.00101 12.4314L1.67696 12.1288L1.71747 11.6325L1.87139 11.4711L3.14329 10.5996L3.13924 10.6036Z"
+              fill="#D97757"
+            />
+          </svg>
+        </DropdownButtonItemIcon>
+        <DropdownButtonItemText>
+          <DropdownButtonItemTextSubtle>Open in</DropdownButtonItemTextSubtle> Claude
+        </DropdownButtonItemText>
+      </DropdownButtonItem>
+      <DropdownButtonItem value="chat-gpt" isExternalLink>
+        <DropdownButtonItemIcon>
+          <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none">
+            <g clip-path="url(#clip0_2771_126147)">
+              <path
+                d="M14.853 6.54857C15.216 5.45907 15.091 4.26557 14.5105 3.27457C13.6375 1.75457 11.8825 0.972574 10.1685 1.34057C9.40596 0.481574 8.31046 -0.00692579 7.16196 7.42116e-05C5.40996 -0.00392579 3.85546 1.12407 3.31646 2.79107C2.19096 3.02157 1.21946 3.72607 0.650955 4.72457C-0.228545 6.24057 -0.0280446 8.15157 1.14696 9.45157C0.783955 10.5411 0.908955 11.7346 1.48946 12.7256C2.36246 14.2456 4.11746 15.0276 5.83146 14.6596C6.59346 15.5186 7.68946 16.0071 8.83796 15.9996C10.591 16.0041 12.146 14.8751 12.685 13.2066C13.8105 12.9761 14.782 12.2716 15.3505 11.2731C16.229 9.75707 16.028 7.84757 14.8535 6.54757L14.853 6.54857ZM8.83896 14.9541C8.13746 14.9551 7.45796 14.7096 6.91946 14.2601C6.94396 14.2471 6.98646 14.2236 7.01396 14.2066L10.2 12.3666C10.363 12.2741 10.463 12.1006 10.462 11.9131V7.42157L11.8085 8.19907C11.823 8.20607 11.8325 8.22007 11.8345 8.23607V11.9556C11.8325 13.6096 10.493 14.9506 8.83896 14.9541ZM2.39696 12.2026C2.04546 11.5956 1.91896 10.8841 2.03946 10.1936C2.06296 10.2076 2.10446 10.2331 2.13396 10.2501L5.31996 12.0901C5.48146 12.1846 5.68146 12.1846 5.84346 12.0901L9.73296 9.84407V11.3991C9.73396 11.4151 9.72646 11.4306 9.71396 11.4406L6.49346 13.3001C5.05896 14.1261 3.22696 13.6351 2.39746 12.2026H2.39696ZM1.55846 5.24807C1.90846 4.64007 2.46096 4.17507 3.11896 3.93357C3.11896 3.96107 3.11746 4.00957 3.11746 4.04357V7.72407C3.11646 7.91107 3.21646 8.08457 3.37896 8.17707L7.26846 10.4226L5.92196 11.2001C5.90846 11.2091 5.89146 11.2106 5.87646 11.2041L2.65546 9.34307C1.22396 8.51407 0.732955 6.68257 1.55796 5.24857L1.55846 5.24807ZM12.6215 7.82257L8.73196 5.57657L10.0785 4.79957C10.092 4.79057 10.109 4.78907 10.124 4.79557L13.345 6.65507C14.779 7.48357 15.2705 9.31807 14.442 10.7521C14.0915 11.3591 13.5395 11.8241 12.882 12.0661V8.27557C12.8835 8.08857 12.784 7.91557 12.622 7.82257H12.6215ZM13.9615 5.80557C13.938 5.79107 13.8965 5.76607 13.867 5.74907L10.681 3.90907C10.5195 3.81457 10.3195 3.81457 10.1575 3.90907L6.26796 6.15507V4.60007C6.26696 4.58407 6.27446 4.56857 6.28696 4.55857L9.50746 2.70057C10.942 1.87307 12.776 2.36557 13.603 3.80057C13.9525 4.40657 14.079 5.11607 13.9605 5.80557H13.9615ZM5.53596 8.57707L4.18896 7.79957C4.17446 7.79257 4.16496 7.77857 4.16296 7.76257V4.04307C4.16396 2.38707 5.50746 1.04507 7.16346 1.04607C7.86396 1.04607 8.54196 1.29207 9.08046 1.74007C9.05596 1.75307 9.01396 1.77657 8.98596 1.79357L5.79996 3.63357C5.63696 3.72607 5.53696 3.89907 5.53796 4.08657L5.53596 8.57607V8.57707ZM6.26746 7.00007L7.99996 5.99957L9.73246 6.99957V9.00007L7.99996 10.0001L6.26746 9.00007V7.00007Z"
+                fill="#262626"
+              />
+            </g>
+            <defs>
+              <clipPath id="clip0_2771_126147">
+                <rect width="16" height="16" fill="white" />
+              </clipPath>
+            </defs>
+          </svg>
+        </DropdownButtonItemIcon>
+        <DropdownButtonItemText>
+          <DropdownButtonItemTextSubtle>Open in</DropdownButtonItemTextSubtle> ChatGPT
+        </DropdownButtonItemText>
+      </DropdownButtonItem>
+    </>
+  );
+}
+
+export function APIReferenceAIDropdown() {
+  return (
+    <DropdownButton id="ai-dropdown-button">
+      <DropdownButtonPrimaryAction>
+        <CopyIcon size={16} />
+        <DropdownButtonPrimaryActionText>Copy Markdown</DropdownButtonPrimaryActionText>
+      </DropdownButtonPrimaryAction>
+      <DropdownButtonTrigger />
+      <DropdownButtonMenu>
+        <AIDropdownOptions />
+        <DropdownButtonDivider />
+        <DropdownButtonItem value="copy-as-markdown" isExternalLink>
+          <DropdownButtonItemIcon>
+            <CopyIcon size={16} />
+          </DropdownButtonItemIcon>
+          <DropdownButtonItemText>Copy Markdown</DropdownButtonItemText>
+        </DropdownButtonItem>
+        <DropdownButtonItem value="view-as-markdown" isExternalLink>
+          <DropdownButtonItemIcon>
+            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none">
+              <path
+                d="M14.8447 3.33301C15.151 3.33301 15.4455 3.45527 15.6621 3.67188C15.8785 3.88844 16 4.18213 16 4.48828V12.0254C15.9997 12.3315 15.8777 12.6254 15.6611 12.8418C15.4446 13.0581 15.1508 13.1797 14.8447 13.1797H1.15527C0.848967 13.1797 0.55449 13.0584 0.337891 12.8418C0.121288 12.6252 0 12.3307 0 12.0244V4.48828C1.09706e-05 4.18213 0.121501 3.88844 0.337891 3.67188C0.554493 3.45527 0.848951 3.33301 1.15527 3.33301H14.8447ZM1.15527 4.10254C1.10457 4.10245 1.0537 4.11247 1.00684 4.13184C0.960202 4.15116 0.917554 4.17917 0.881836 4.21484C0.845984 4.2507 0.817213 4.29396 0.797852 4.34082C0.778601 4.38756 0.769447 4.43773 0.769531 4.48828V12.0254C0.76962 12.0759 0.779409 12.1262 0.798828 12.1729C0.81827 12.2196 0.846978 12.2621 0.882812 12.2979C0.918602 12.3335 0.961134 12.3616 1.00781 12.3809C1.05454 12.4001 1.10474 12.4102 1.15527 12.4102H14.8447C14.9467 12.4101 15.045 12.3699 15.1172 12.2979C15.1893 12.2258 15.2293 12.1274 15.2295 12.0254V4.48828C15.2296 4.43774 15.2204 4.38755 15.2012 4.34082C15.1819 4.29403 15.1529 4.25166 15.1172 4.21582C15.0814 4.17999 15.0389 4.15126 14.9922 4.13184C14.9455 4.11249 14.8952 4.10258 14.8447 4.10254H1.15527ZM5.38477 7.56348L6.92285 5.64062H8.46094V10.8721H6.92285V7.87109L5.38477 9.79492L3.8457 7.87109V10.8711H2.30762V5.63965H3.8457L5.38477 7.56348ZM12.6924 8.33301H14.2305L11.9229 10.8711L9.61523 8.33301H11.1533V5.64062H12.6924V8.33301Z"
+                fill="#262626"
+              />
+            </svg>
+          </DropdownButtonItemIcon>
+          <DropdownButtonItemText>View as Markdown</DropdownButtonItemText>
+        </DropdownButtonItem>
+      </DropdownButtonMenu>
+    </DropdownButton>
+  );
+}

package/stl-docs/components/ClientRouterHead.astro

@@ -0,0 +1,41 @@
+---
+import { ClientRouter } from 'astro:transitions';
+import Default from '@astrojs/starlight/components/Head.astro';
+---
+
+<style is:global>
+  /* Disable native View Transitions animations */
+  :root::view-transition-old(root),
+  :root::view-transition-new(root) {
+    animation: none;
+  }
+  :root::view-transition-group(root) {
+    animation-duration: 0s;
+  }
+</style>
+
+<script>
+  console.log('[EXPERIMENTAL] using client router');
+</script>
+<script>
+  function setNavLinksMode(doc: Document) {
+    let mode = localStorage.getItem('stl-nav-links-mode');
+    // initial guess
+    if (mode === null) {
+      mode = window.innerWidth < 1000 ? 'mobile' : 'desktop';
+    }
+    doc.documentElement.classList.add('stl-nav-links-mode-' + mode);
+  }
+
+  setNavLinksMode(document);
+
+  // https://docs.astro.build/en/guides/view-transitions/#astrobefore-swap
+
+  document.addEventListener('astro:before-swap', (event) => {
+    setNavLinksMode(event.newDocument);
+  });
+</script>
+
+<ClientRouter />
+
+<Default />

package/stl-docs/components/Header.astro

@@ -0,0 +1,91 @@
+---
+import config from 'virtual:starlight/user-config';
+
+import { HEADER_LAYOUT } from 'virtual:stl-stl-starlight-virtual-module';
+import DefaultHeader from './headers/DefaultHeader.astro';
+import StackedHeader from './headers/StackedHeader.astro';
+
+/**
+ * Render the `Search` component if Pagefind is enabled or the default search component has been overridden.
+ */
+const shouldRenderSearch = !!(
+  config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro'
+);
+---
+
+{
+  HEADER_LAYOUT === 'stacked' ? (
+    <StackedHeader shouldRenderSearch={shouldRenderSearch} />
+  ) : (
+    <DefaultHeader shouldRenderSearch={shouldRenderSearch} />
+  )
+}
+
+<style is:global>
+  @layer starlight.core {
+    header {
+      border-color: var(--sl-color-hairline);
+
+      &.header {
+        border-bottom-color: var(--sl-color-hairline);
+      }
+    }
+
+    .header {
+      display: flex;
+      gap: var(--sl-nav-gap);
+      justify-content: space-between;
+      align-items: center;
+      height: 100%;
+      width: 100%;
+    }
+    .title-wrapper {
+      /* Prevent long titles overflowing and covering the search and menu buttons on narrow viewports. */
+      overflow: clip;
+      /* Avoid clipping focus ring around link inside title wrapper. */
+      padding: 0.25rem;
+      padding-left: 0;
+      margin: -0.25rem;
+      min-width: 0;
+    }
+
+    .default-tabs-container {
+      justify-content: flex-end;
+    }
+
+    .split-tabs-container {
+      display: flex;
+      max-width: 480px;
+      flex: 1;
+
+      button {
+        max-width: unset;
+        width: 100%;
+        flex: 1;
+      }
+    }
+
+    .left-group {
+      display: flex;
+      align-items: center;
+      gap: var(--sl-nav-gap);
+      flex-shrink: 0;
+    }
+
+    .right-group,
+    .social-icons {
+      gap: var(--sl-nav-gap);
+      align-items: center;
+    }
+
+    .right-group > div {
+      gap: var(--sl-nav-gap);
+    }
+
+    @media (min-width: 50rem) {
+      .default-tabs-container {
+        min-width: 440px;
+      }
+    }
+  }
+</style>

package/stl-docs/components/Sidebar.astro

@@ -0,0 +1,11 @@
+---
+import Default from '@astrojs/starlight/components/Sidebar.astro';
+import SDKSelect from '../../plugin/components/SDKSelect.astro';
+import HeaderLinks from './headers/HeaderLinks.astro';
+---
+
+<div class="stl-sidebar-header-links">
+  <HeaderLinks />
+</div>
+<SDKSelect />
+<Default><slot /></Default>