### Install and Run xyd CLI

Source: https://context7.com/livesession/xyd/llms.txt

Install the xyd CLI globally using npm or bun. Use the `xyd` command to start the dev server, build static files, serve built output, or migrate from other documentation frameworks.

```bash
bun add -g xyd-js
# or
npm install -g xyd-js

xyd
# equivalent to:
xyd dev

xyd build

xyd serve

xyd migrateme ./path/to/mintlify-docs    # local path
xyd migrateme https://github.com/org/repo  # GitHub repo

xyd install components

xyd --version

xyd --verbose
```

--------------------------------

### Render Guide Card with Custom Element Syntax

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/guide-card.md

This example demonstrates rendering a Guide Card using a custom element syntax, often used in templating or specific frameworks. The icon prop is passed as a string.

```tsx
:::guide-card{title="Getting Started" icon="code" href="/guides/quickstart"}
Start your journey with our comprehensive quickstart guide.
:::
```

--------------------------------

### xyd.opencli.spice install Usage

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-opencli-remark/src/__fixtures__/1.code-block-format/input.md

Displays the usage instructions, description, arguments, and options for the 'xyd.opencli.spice install' command.

```sh
Usage: {opencli.current.usage}

{opencli.current.description}

Arguments:
{opencli.current.arguments}

Options:
{opencli.current.options}
```

--------------------------------

### Render Guide Card with Props

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/guide-card.md

This example shows how to render a Guide Card component using its props directly in JSX. Ensure the GuideCard component is imported.

```tsx
import GuideCard from "@components/writer/GuideCard/GuideCard";

<GuideCard
  title="Routing Guide"
  icon="code"
  href="/guides/routing"
>
  Learn about file-convention and settings-based routing in xyd.
</GuideCard>
```

--------------------------------

### Example: Register Resources and Tools

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-mcp/README.md

A complete example demonstrating the initialization of an McpServer and the registration of both API reference resources and tools from a local OpenAPI JSON file.

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { mcpUniformResources, mcpUniformTools } from "@xyd-js/mcp";

const server = new McpServer({ name: "example", version: "0.0.0" });
await mcpUniformResources(server, "./demo/simple/openapi.json");
await mcpUniformTools(server, "./demo/simple/openapi.json", "my-access-token");
```

--------------------------------

### Install a Package with spice

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-opencli-remark/src/__fixtures__/1.code-block-format/output.md

Use this command to install a package. Specify the package name as an argument. The -g or --global flag can be used for global installation.

```sh
Usage: spice install [options] <package>

Install a package

Arguments:
	package                       Package name

Options:
	-g, --global                  Install globally

```

--------------------------------

### Install Project Dependencies

Source: https://github.com/livesession/xyd/blob/master/apps/apidocs-demo/README.md

Run this command in your terminal to install all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Guide Card Component Examples

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-content/packages/md/plugins/composer/__fixtures__/4.example-groups/input.md

Shows two versions of a Guide Card component. Use these as a basis for creating your own card components.

```jsx
function GuideCard() {
  return <div> Guide Card </div>
}
```

```tsx
function GuideCardV2() {
  return <div> Guide Card V2 </div>
}
```

--------------------------------

### Start Development Mode

Source: https://github.com/livesession/xyd/blob/master/CONTRIBUTING.md

Run this command to start the project in development mode, enabling hot-reloading and other development-specific features.

```bash
XYD_DEV_MODE=1 pnpm run dev
```

--------------------------------

### Install @xyd-js/ask-ai

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-ask-ai/README.md

Install the package using npm.

```bash
npm install @xyd-js/ask-ai
```

--------------------------------

### Build and Start MCP Server

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-mcp-server/README.md

Commands to build the project and start the MCP server, optionally specifying the port and the Uniform source file (OpenAPI or GraphQL).

```bash
# Build
bun run build

# Start (OpenAPI)
PORT=3000 bun run start ./demo/simple/openapi.json

# Or with GraphQL schema
# PORT=3000 bun run start ./path/to/schema.graphql
```

--------------------------------

### Python SDK Get Settings Snippet

Source: https://github.com/livesession/xyd/blob/master/__tests__/__fixtures__/node-support/markdown.md

Shows how to retrieve settings using the Python SDK. Ensure the SDK is installed and configured.

```python
snippet = await snippets.py.getSettings()
```

--------------------------------

### Install a package

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-opencli-remark/src/__fixtures__/8.multiple-placeholders/output.md

Installs a specified package using the spice CLI.

```APIDOC
## spice install [options] <package>

### Description
Install a package

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
- **package** (string) - Required - The name of the package to install.

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```bash
spice install my-package
```

### Response
#### Success Response (0)
- Installation successful message

#### Response Example
```
Package 'my-package' installed successfully.
```
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/livesession/xyd/blob/master/DEVELOPMENT.md

Installs all project dependencies using pnpm. Ensure Node.js and pnpm are installed.

```bash
pnpm i
```

--------------------------------

### Install a Package with Spice CLI

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-opencli-remark/src/__fixtures__/8.multiple-placeholders/output.md

Use this command to install a package. Specify the package name and any desired options.

```bash
spice install [options] <package>
Install a package
```

--------------------------------

### spice install

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-opencli-remark/src/__fixtures__/1.code-block-format/output.md

Installs a specified package using the Xyd OpenCLI spice command. Supports global installation.

```APIDOC
## spice install

### Description
Installs a package using the spice command.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Arguments
- **package** (string) - Required - Package name to install.

#### Options
- **-g, --global** (boolean) - Install globally.
```

--------------------------------

### Install and Run xyd Dev Server

Source: https://github.com/livesession/xyd/blob/master/README.md

Install xyd globally using Bun and run the development server. Node.js version 22.12+ is required.

```bash
bun add -g xyd-js
```

```bash
xyd 
```

```bash
xyd build
```

--------------------------------

### Install Dependencies and Build Project

Source: https://github.com/livesession/xyd/blob/master/CONTRIBUTING.md

Use these commands to install project dependencies and build all packages within the monorepo.

```bash
pnpm install

pnpm run build
```

--------------------------------

### Component Composition Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/components-api.md

Demonstrates how to use composition to customize component API pages, including embedding examples within the documentation.

```md
---
title: Callouts
icon: info
layout: wide
uniform: "@components/writer/Callout/Callout.tsx"
---

### Examples
:::callout
Note that you must have an Admin or Owner role to manage webhook settings.
:::


@.examples
```tsx
<Callout>
Note that you must have an Admin or Owner role to manage webhook settings.
</Callout>
```

```md
:::callout
Note that you must have an Admin or Owner role to manage webhook settings.
:::
```
@end
```

--------------------------------

### Install @xyd-js/mcp

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-mcp/README.md

Install the package using bun. Requires a Bun or Node.js compatible ESM environment.

```bash
bun add @xyd-js/mcp
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-mcp-server/README.md

Installs project dependencies using the Bun package manager.

```bash
bun install
```

--------------------------------

### Install xyd-js with yarn

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-content/packages/md/plugins/output-variables/__fixtures__/2.multiple-vars/input.md

Install the xyd-js package globally using yarn.

```bash
yarn global add xyd-js
```

--------------------------------

### Routing Configuration Example

Source: https://github.com/livesession/xyd/blob/master/__tests__/__fixtures__/node-support/pages-and-routing.md

Configure navigation in docs.json. Groups organize pages and define their paths in the sidebar.

```json
{
  "sidebar": [
    {
      "group": "Get Started",
      "icon": "code",
      "pages": [
          "your-page",
          "folder-name/your-page-within-folder"
      ]
    }
    // ... other groups
  ]
}
```

--------------------------------

### Example Supademo Embed

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/integrations/apps/supademo.md

An example of embedding a Supademo demo directly in the documentation using a specific demo ID.

```html
<span data-supademo-demo="cmdvyvj6r6liu9f96jj5xg65n">

:::button
View Demo
:::

</span>
```

--------------------------------

### Example React Component and Generated Documentation

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/components-api.md

An example of a React component (`Button`) with TypeScript props and JSDoc comments, demonstrating how it will be documented. The generated documentation includes component name, description, props info (name, type, required status, description), and usage examples.

```APIDOC
## Example

Here's a full example of a React component and how it will be documented:

```tsx
// components/Button.tsx
import React from 'react'

interface ButtonProps {
  /** The text to display inside the button */
  children: React.ReactNode

  /** The type of button */
  variant?: 'primary' | 'secondary'

  /** Whether the button is disabled */
  disabled?: boolean

  /** Click handler */
  onClick?: () => void
}

/**
 * @category Component
 */
export const Button = ({ 
  children, 
  variant = 'primary',
  disabled = false,
  onClick 
}: ButtonProps) => {
  return (
    <button 
      className={`btn-${variant}`}
      disabled={disabled}
      onClick={onClick}
    >
      {children}
    </button>
  )
}
```

This will generate an API documentation page that shows:
- Component name and description
- Props info with:
  - Prop name
  - Type
  - Required status
  - Description from TypeDoc comments
- Usage examples
- TypeScript interface definitions
```

--------------------------------

### Run Development Server for Styles

Source: https://github.com/livesession/xyd/blob/master/DEVELOPMENT.md

Starts the development server specifically for style-related packages. This is useful for iterating on CSS or styling components.

```bash
pnpm run dev:styles
```

--------------------------------

### Install xyd CLI

Source: https://github.com/livesession/xyd/blob/master/__tests__/__fixtures__/node-support/introduction.md

Installs the xyd command-line tool globally using npm.

```bash
npm i -g xyd-js
```

--------------------------------

### Install xyd-js with pnpm

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-content/packages/md/plugins/output-variables/__fixtures__/2.multiple-vars/input.md

Install the xyd-js package globally using pnpm.

```bash
pnpm add -g xyd-js
```

--------------------------------

### Example OpenCLI Plugin Configuration

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-opencli-remark/README.md

Illustrates how to configure the remarkOpencliDocs plugin with specific CLI sources, including local paths and URLs.

```typescript
remarkOpencliDocs({
  xyd: { source: './xyd-cli.json' },
  npm: { source: 'https://example.com/npm-cli.json' }
})
```

--------------------------------

### Markdown and MDX Content Examples

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/writing-quickstart.md

Demonstrates basic markdown and MDX syntax for content, including callouts.

```md
# Quickstart

This is a quickstart guide for the `xyd` project.

:::
callout
Tip: You can use the React `<Callout>` component to render a callout too
:::

```

```mdx
# Quickstart

This is a quickstart guide for the `xyd` project.

<Callout>
Tip: You can use the React `<Callout>` component to render a callout too
</Callout>

```

--------------------------------

### Install xyd CLI

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/quickstart.md

Install the xyd CLI globally using your preferred package manager. Note potential issues with Bun v1.2.21.

```bash
bun add -g xyd-js
```

```bash
pnpm add -g xyd-js
```

```bash
npm i -g xyd-js
```

--------------------------------

### Tabs Component Examples

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/tabs.md

Demonstrates the usage of the Tabs component with secondary styling to present different command-line build options.

```md
:::tabs{kind="secondary"}
1. [bunx](type=bunx)
    ```bash
    $ bunx xyd-js build
    ```

2. [npx](type=npx)
    ```bash
    $ npx xyd-js build
    ```

3. [CLI](type=xyd)
    ```bash
    $ xyd build
    ```
:::
```

--------------------------------

### Code Grouping for Installation

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/developer-content.md

Group multiple code blocks using the `code-group` component, useful for showing installation commands for different package managers.

```bash
bun add -g xyd-js
```

```bash
npm i -g xyd-js
```

--------------------------------

### Include Code Examples in Documentation

Source: https://github.com/livesession/xyd/blob/master/apps/docs/reference/functions/uniform.md

Embed code examples within your documentation using TypeDoc comments. This allows @uniform to extract and display them.

```typescript
/**
 * @example
 * ```ts
 * const result = myFunction("example");
 * console.log(result);
 * ```
 */
```

--------------------------------

### Tip Callout Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/callouts.md

Displays a tip callout. Use this to provide helpful suggestions or shortcuts.

```md
:::callout{kind="tip"}
Tip: you must have an Admin or Owner role to manage webhook settings.
:::
```

--------------------------------

### Example React Component for API Docs

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/components-api.md

This is a complete example of a React component with TypeDoc comments for its props. It demonstrates how the component and its props will be documented.

```tsx
// components/Button.tsx
import React from 'react'

interface ButtonProps {
  /** The text to display inside the button */
  children: React.ReactNode

  /** The type of button */
  variant?: 'primary' | 'secondary'

  /** Whether the button is disabled */
  disabled?: boolean

  /** Click handler */
  onClick?: () => void
}

/**
 * @category Component
 */
export const Button = ({
  children,
  variant = 'primary',
  disabled = false,
  onClick
}: ButtonProps) => {
  return (
    <button
      className={`btn-${variant}`}
      disabled={disabled}
      onClick={onClick}
    >
      {children}
    </button>
  )
}
```

--------------------------------

### Install xyd-js CLI from Verdaccio

Source: https://github.com/livesession/xyd/blob/master/DEVELOPMENT.md

Installs the xyd-js CLI globally using a specific npm registry (Verdaccio). This is useful for testing local package builds.

```bash
npm_config_registry=http://localhost:4873 bun add -g xyd-js
```

```bash
npm_config_registry=http://localhost:4873 npm i -g xyd-js
```

```bash
npm_config_registry=http://localhost:4873 pnpm add -g xyd-js
```

--------------------------------

### Basic React Component Example

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-content/packages/md/plugins/output-variables/__fixtures__/2.multiple-vars/input.md

A simple React component that renders a 'Hello World' message.

```tsx
function() {
    return <div> Hello World </div>
  }
```

--------------------------------

### esbuild Plugin Configuration

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-source-react-runtime/README.md

Set up the esbuild build process to use the xydSourceReactRuntimeEsbuild plugin. This example demonstrates a basic esbuild build configuration.

```javascript
import * as esbuild from "esbuild";
import { xydSourceReactRuntimeEsbuild } from "@xyd-js/source-react-runtime/esbuild";

await esbuild.build({
  entryPoints: ["src/index.ts"],
  outfile: "dist/index.js",
  bundle: true,
  format: "esm",
  plugins: [
    xydSourceReactRuntimeEsbuild(),
  ],
});
```

--------------------------------

### Run Docker Container

Source: https://github.com/livesession/xyd/blob/master/apps/apidocs-demo/README.md

Starts a Docker container from the built image and maps port 3000 on your host to port 3000 in the container.

```bash
docker run -p 3000:3000 my-app
```

--------------------------------

### Basic Callout Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/callouts.md

Displays a default callout. Ensure the content is relevant to the user's role.

```md
:::callout
You must have an Admin or Owner role to manage webhook settings.
:::
```

--------------------------------

### Clone Starter Project

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/quickstart.md

Clone the starter project repository and navigate into the project directory.

```bash
git clone https://github.com/xyd-js/starter
cd starter
```

--------------------------------

### Example of Callback-based @out with Props

Source: https://github.com/livesession/xyd/blob/master/apps/docs/reference/functions/out.md

Shows how to use a callback for an output variable, including passing props and embedding content within the callback structure.

```mdx
@.examples(title="Samples")
```md
:::callout
Note that you must have an Admin or Owner role to manage webhook settings.
:::
```
@end
```

--------------------------------

### Run Documentation Development Server

Source: https://github.com/livesession/xyd/blob/master/DEVELOPMENT.md

Starts the development server for documentation locally without building the main CLI package. Ensure you are in the 'docs/' directory.

```bash
cd docs
node packages/xyd-cli/dist/index.js
```

--------------------------------

### Run xyd Dev Server

Source: https://github.com/livesession/xyd/blob/master/__tests__/__fixtures__/node-support/introduction.md

Starts the xyd development server, which includes hot reloading for a seamless development experience.

```bash
xyd
```

--------------------------------

### GFM Markdown Example

Source: https://github.com/livesession/xyd/blob/master/__tests__/__fixtures__/node-support/markdown.md

Demonstrates basic GitHub Flavored Markdown syntax including headings, text formatting, lists, quotes, and images.

```markdown
# Heading1
 
Hello World, **Bold**, _Italic_, ~~Hidden~~
 
1. First
2. Second
 
> Quote here
 
![alt](/image.png)
```

--------------------------------

### Configure Base URL for llms.txt

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/llms-txt.md

This will generate URLs like `https://docs.example.com/docs/getting-started` instead of relative paths like `/docs/getting-started`.

```json
{
  "ai": {
    "llmsTxt": {
      "title": "My Documentation",
      "baseUrl": "https://docs.example.com"
    }
  }
}
```

--------------------------------

### CSV Data for Table

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/tables.md

This example shows how to structure data in CSV format to be rendered as a table. It includes headers, descriptions, and markdown representations.

```csv
:::table
```
[
    ["Syntax", "Description", "Markdown"],
    ["Header", "Title", "`#`"],
    ["Paragraph", "Text", "`*`"]
]
```
:::
```

--------------------------------

### Build Demo Application

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-ask-ai/README.md

Build the demo application using the provided npm script.

```bash
npm run build:demo
```

--------------------------------

### LaTeX Display Math Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/developer-content.md

Render display math equations using LaTeX by wrapping the equation in double dollar signs ($$).

```latex
$$
\frac{d}{dx}\left(\int_0^x f(t) \, dt\right) = f(x)
$$
```

--------------------------------

### Initialize Theme and App Display

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-components/docs/hierarchy.html

Sets the theme based on local storage or OS preference, hides the body, and then shows the app page after a delay or immediately if the app is available. Use this for initial application setup.

```javascript
document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";
document.body.style.display="none";
setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)
```

--------------------------------

### Build Docs with bunx

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/deploy.md

Use this command to build your xyd documentation. It produces static files in the `.xyd/build/client` folder, which can be served locally or deployed to production.

```bash
$ bunx xyd-js build
```

--------------------------------

### Custom Login Component Setup

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/access-control.md

Configure a custom login component by specifying its path in `docs.json`. The component should use the `useAccessControl` hook from `@xyd-js/client-api`.

```json
{
  "accessControl": {
    "login": "./custom-login.tsx"
  }
}
```

--------------------------------

### Component Configuration Setup

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/components-api.md

To create an API documentation page for a component, specify its path in the meta using `uniform`. Mark the component function in code using JSDoc tags like `@category Component` or `@component`.

```APIDOC
## Setup Component Configuration

To create an API documentation page for a component, specify its path in the meta using [`uniform`](/reference/core/pagemeta):

```yaml
---
title: Callouts
icon: info
uniform: "<PATH TO COMPONENT>"
---
```

Mark component function in code:

```tsx
/**
 * @category Component
 */
export function Button() {
  ...
}
```

alternatively using`@component`:

```tsx
/**
 * @component
 */
export function Button() {
  ...
}
```
```

--------------------------------

### Example llms.txt Structure

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/llms-txt.md

This structured approach allows LLMs to efficiently process your documentation at a high level and locate relevant content for user queries.

```md
# My Documentation Site

## Documentation

- [Getting Started](https://example.com/docs/getting-started): Quick start guide for new users
- [API Reference](https://example.com/docs/api): Complete API endpoint documentation
- [Configuration](https://example.com/docs/config): Configuration options and settings
```

--------------------------------

### Apply a Theme to Your Docs

Source: https://github.com/livesession/xyd/blob/master/__tests__/__fixtures__/node-support/make-docs-yours.md

Use pre-built themes to quickly style your documentation. Choose from an available collection.

```json
{
  "theme": {
    "name": "poetry"
  }
}
```

--------------------------------

### Run Demo API and MCP Server

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-mcp-server/README.md

Commands to run the demo API server in a separate terminal and then start the MCP server using the demo's OpenAPI document. Also shows how to open the MCP Inspector.

```bash
# Run demo API (separate terminal)
PORT=5050 bun demo/simple/server.ts

# Start MCP server using demo OpenAPI
PORT=3000 bun run start ./demo/simple/openapi.json

# Open MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:3000/mcp
```

--------------------------------

### Build for Production

Source: https://github.com/livesession/xyd/blob/master/apps/apidocs-demo/README.md

Execute this command to create an optimized production build of your application.

```bash
npm run build
```

--------------------------------

### Guide Card React Component

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-content/packages/md/plugins/composer/__fixtures__/2.single-example-with-name/input.md

A basic React component for a guide card. Ensure React is available in your project.

```jsx
function GuideCard() {
  return <div> Guide Card </div>
}
```

--------------------------------

### xyd Configuration (`docs.json`)

Source: https://context7.com/livesession/xyd/llms.txt

The `docs.json` file configures theme, navigation, API sources, integrations, SEO, and access control. This example shows theme customization, SEO settings, AI-related configurations, and advanced options like Vite server settings.

```json
{
  "$schema": "https://xyd.dev/public/docs.json",

  "theme": {
    "name": "opener",
    "logo": {
      "light": "/public/assets/logo.svg",
      "dark": "/public/assets/logo-dark.svg",
      "page": "/docs/guides/introduction",
      "href": "https://example.com"
    },
    "favicon": "/public/assets/logo.svg",
    "appearance": {
      "colorScheme": "os",
      "colors": {
        "primary": "#3b82f6",
        "dark": "#000",
        "light": "#fff"
      },
      "cssTokens": { "--dark100": "#000" },
      "header": { "type": "classic", "externalArrow": true },
      "sidebar": { "scrollShadow": true },
      "buttons": { "rounded": "lg" }
    },
    "coder": {
      "lines": true,
      "scroll": true,
      "syntaxHighlight": "github-dark"
    }
  },

  "seo": {
    "domain": "https://docs.example.com",
    "metatags": {
      "og:image": "https://docs.example.com/og.png"
    }
  },

  "ai": {
    "llmsTxt": {
      "title": "My Docs",
      "baseUrl": "https://docs.example.com",
      "summary": "Documentation for the Example project"
    }
  },

  "advanced": {
    "basename": "/docs",
    "vite": {
      "server": { "allowedHosts": ["my-remote-env.example.com"] }
    }
  }
}
```

--------------------------------

### Build Docs with npx

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/deploy.md

Use this command to build your xyd documentation. It produces static files in the `.xyd/build/client` folder, which can be served locally or deployed to production.

```bash
$ npx xyd-js build
```

--------------------------------

### Install xyd-js Globally

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-content/packages/md/plugins/output-variables/__fixtures__/1.simple/input.md

Install the xyd-js package globally using your preferred package manager. This makes the xyd-js command-line tools available system-wide.

```bash
npm i -g xyd-js
```

```bash
yarn global add xyd-js
```

```bash
pnpm add -g xyd-js
```

--------------------------------

### Configure LaunchDarkly Integration

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/integrations/abtesting/launchdarkly.md

Add this configuration to your `docs.json` to enable the LaunchDarkly integration. The `env` attribute is required.

```json
{
  "integrations": {
    "abtesting": {
      "providers": {
        "launchdarkly": {
            "env": "required"
        }
      }
    }
  }
}
```

--------------------------------

### Run Demo Application

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-ask-ai/README.md

Run the demo application using Vite with the provided npm script.

```bash
npm run dev:demo
```

--------------------------------

### Example JWT Payload

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/access-control.md

This is an example of a JWT payload that includes user identification and group information. Ensure the `groupsClaim` in your `docs.json` matches the key used for groups in your JWT.

```json
{
  "sub": "user-123",
  "groups": ["admin", "staff"],
  "exp": 1735689600,
  "iat": 1735603200
}
```

--------------------------------

### Define Custom Output Variables in Settings API

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/special-symbols.md

Define custom output variables in the Settings API. The provided `Examples` function will handle the logic for the 'examples' output variable.

```tsx
export default {
  outputVariables: {
    examples: Examples
  }
}

function Examples({title, children}) {
  // your custom logic here
}
```

--------------------------------

### Build Docs with xyd CLI

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/deploy.md

Use this command to build your xyd documentation. It produces static files in the `.xyd/build/client` folder, which can be served locally or deployed to production.

```bash
$ xyd build
```

--------------------------------

### Graphviz Diagram Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/developer-content.md

Embed Graphviz diagrams in your Markdown by wrapping the Graphviz DOT language syntax in a 'dot' code block. This example uses subgraphs and specific node/edge styling.

```dot
digraph G {
	fontname="Helvetica,Arial,sans-serif"
	node [fontname="Helvetica,Arial,sans-serif"]
	edge [fontname="Helvetica,Arial,sans-serif"]

	subgraph cluster_0 {
		style=filled;
		color=lightgrey;
		node [style=filled,color=white];
		a0 -> a1 -> a2 -> a3;
		label = "process #1";
	}

	subgraph cluster_1 {
		node [style=filled];
		b0 -> b1 -> b2 -> b3;
		label = "process #2";
		color=blue
	}
	start -> a0;
	start -> b0;
	a1 -> b3;
	b2 -> a3;
	a3 -> a0;
	a3 -> end;
	b3 -> end;

	start [shape=Mdiamond];
	end [shape=Msquare];
}
```

--------------------------------

### OAuth UserInfo Endpoint Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/access-control.md

Example JSON response from a userinfo endpoint for OAuth. This structure is expected by xyd to retrieve user groups. If your `groupsClaim` is set to `roles`, xyd will look for `response.roles`. Otherwise, it falls back to `response.groups` or `response[groupsClaim]`.

```json
{
  "sub": "user-123",
  "email": "user@example.com",
  "roles": ["admin", "staff"]
}
```

--------------------------------

### Get Current Encryption Byte

Source: https://github.com/livesession/xyd/blob/master/playwright-report/index.html

Retrieves the current byte used for XOR encryption.

```javascript
function r0(l){
const s=l.keys[2]|2;
return i0(Math.imul(s,s^1)>>>8)
}
```

--------------------------------

### Start Development Server

Source: https://github.com/livesession/xyd/blob/master/apps/apidocs-demo/README.md

Use this command to launch the development server with Hot Module Replacement (HMR) enabled. The application will be accessible at http://localhost:5173.

```bash
npm run dev
```

--------------------------------

### Auth Server JWT Signing Example (Node.js)

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/access-control.md

Example Node.js code for signing JWTs. This function generates a JWT with standard claims like `iat` and `exp`, and includes a `payload` which can contain user information and groups. If your JWT uses a different claim name for groups (e.g., `roles`), update `groupsClaim` in your `docs.json` accordingly.

```javascript
import { createHmac } from "node:crypto v2";

const JWT_SECRET = process.env.AUTH_SECRET;

function signJWT(payload) {
  const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" }))
    .toString("base64url");
  const body = Buffer.from(JSON.stringify({
    ...payload,
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + 86400,
  })).toString("base64url");
  const sig = createHmac("sha256", JWT_SECRET)
    .update(`${header}.${body}`)
    .digest("base64url");
  return `${header}.${body}.${sig}`;
}

// After user authenticates:
const token = signJWT({ sub: user.id, groups: user.groups });
const callbackUrl = `${DOCS_URL}/auth/jwt-callback?token=${token}&redirect=${redirect}`;
res.redirect(302, callbackUrl);
```

--------------------------------

### Uninstall xyd-js CLI Globally

Source: https://github.com/livesession/xyd/blob/master/DEVELOPMENT.md

Removes the xyd-js CLI package from the global npm installation.

```bash
npm uninstall -g xyd-js
```

--------------------------------

### Build Docker Image

Source: https://github.com/livesession/xyd/blob/master/apps/apidocs-demo/README.md

Builds a Docker image for your application. Tag the image with a name like 'my-app'.

```bash
docker build -t my-app .
```

--------------------------------

### Initialize McpServer and Register Resources/Tools

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-mcp/README.md

Initialize an McpServer and register API reference resources and tools from a Uniform source. An optional token can be provided for authenticated requests.

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { mcpUniformResources, mcpUniformTools } from "@xyd-js/mcp";

const server = new McpServer({ name: "xyd-mcp", version: "0.1.0" });

// Path to a Uniform source (OpenAPI JSON/YAML or GraphQL schema)
const uniformSource = "./openapi.json";

// Register API reference resources (text/markdown) under uri: api-reference://<canonical>
await mcpUniformResources(server, uniformSource);

// Register tools; if your API needs auth, pass a token which will be sent
// as Authorization: Bearer <token> for outgoing requests
await mcpUniformTools(server, uniformSource, process.env.API_TOKEN || "");
```

--------------------------------

### Note Callout Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/callouts.md

Displays a note callout. Use this for supplementary information that users should be aware of.

```md
:::callout{kind="note"}
Note: you must have an Admin or Owner role to manage webhook settings.
:::
```

--------------------------------

### Netlify Deployment Configuration

Source: https://github.com/livesession/xyd/blob/master/apps/docs/guides/deploy.md

Configure your Netlify site to build and deploy xyd documentation. Point to the generated static files in the `.xyd/build/client` directory.

```toml
[build]
command = "bunx xyd-js build"
publish = ".xyd/build/client"
```

--------------------------------

### Example of @out with Embedded Content

Source: https://github.com/livesession/xyd/blob/master/apps/docs/reference/functions/out.md

Demonstrates setting an output variable where the expression itself contains embedded markdown, such as a callout.

```mdx
@out(
    .examples = (
      ```md
      :::callout
      Note that you must have an Admin or Owner role to manage webhook settings.
      :::
      ```
  )
)
```

--------------------------------

### Check Callout Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/callouts.md

Displays a check callout. Use this to confirm successful actions or requirements met.

```md
:::callout{kind="check"}
Check: you must have an Admin or Owner role to manage webhook settings.
:::
```

--------------------------------

### Initialize remark with OpenCLI Docs Plugin

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-opencli-remark/README.md

Configure the remark processor with the remarkOpencliDocs plugin, specifying multiple CLI sources for documentation generation.

```typescript
import { remarkOpencliDocs } from '@xyd-js/opencli-remark';
import remarkFrontmatter from 'remark-frontmatter';
import remarkStringify from 'remark-stringify';
import { remark } from 'remark';

// Configure multiple CLI specs
remark()
  .use(remarkFrontmatter)
  .use(remarkOpencliDocs, {
    xyd: { source: './xyd-cli.json' },
    npm: { source: './npm-cli.json' },
    // Add more CLIs as needed
  })
  .use(remarkStringify)
  .process(markdown);
```

--------------------------------

### Get Request Headers

Source: https://github.com/livesession/xyd/blob/master/playwright-report/index.html

Retrieves request headers from the options object. Handles both object and iterable headers.

```javascript
function Ra({options:l}){const{headers:s}=l;if(s)return Symbol.iterator in s?Object.fromEntries(s):s}
```

--------------------------------

### Build Static Files

Source: https://context7.com/livesession/xyd/llms.txt

Command to build the project for static deployment. Can be run globally or via package managers.

```bash
# Build
xyd build
# or without global install:
bunx xyd-js build
npx  xyd-js build
```

--------------------------------

### Rollup Plugin Configuration

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-source-react-runtime/README.md

Integrate the xydSourceReactRuntime plugin into your Rollup build configuration. This example also includes the @rollup/plugin-typescript.

```javascript
import typescript from "@rollup/plugin-typescript";
import { xydSourceReactRuntime } from "@xyd-js/source-react-runtime";

export default {
  input: "src/index.ts",
  plugins: [
    xydSourceReactRuntime(),
    typescript(),
  ],
};
```

--------------------------------

### Warning Callout Example

Source: https://github.com/livesession/xyd/blob/master/apps/docs/components/callouts.md

Displays a warning callout. Use this to alert users to potential issues or important restrictions.

```md
:::callout{kind="warning"}
Warning: you must have an Admin or Owner role to manage webhook settings.
:::
```

--------------------------------

### Create Range Header Value

Source: https://github.com/livesession/xyd/blob/master/playwright-report/index.html

Creates the value for the Range header based on the start and end points of the data.

```javascript
function y0(l,s=0,r=1){return Object.assign({},Ra(l),{[H2]:p0+"="+(s<0?s:s+"-"+(s+r-1))})}
```

--------------------------------

### Configure Theme and Appearance

Source: https://context7.com/livesession/xyd/llms.txt

Set the theme name and customize appearance, coder settings, and fonts in docs.json.

```json
{
  "theme": {
    "name": "opener",

    "appearance": {
      "colorScheme": "os",
      "colors": { "primary": "#6366f1" },
      "header": { "type": "pad", "buttonSize": "md" },
      "tabs": { "surface": "center" },
      "sidebar": { "scrollShadow": true, "scrollbar": "secondary" },
      "content": { "breadcrumbs": true, "sectionSeparator": true },
      "footer": { "surface": "page" }
    },

    "coder": {
      "lines": false,
      "scroll": true,
      "syntaxHighlight": "github-dark"
    },

    "fonts": {
      "body": { "family": "Inter", "src": "/public/fonts/Inter.woff2", "format": "woff2" },
      "coder": { "family": "Fira Code", "src": "/public/fonts/FiraCode.woff2", "format": "woff2" }
    }
  }
}
```

--------------------------------

### React Scheduler - Get Transition Priority

Source: https://github.com/livesession/xyd/blob/master/playwright-report/index.html

Determines the priority for a transition based on the current mode and transition configuration.

```javascript
function gn(e){return(e.mode&1)===0?1:(ve&2)!==0&&be!==0?be&-be:wh.transition!==null?(kl===0&&(kl=lu()),kl):(e=Ae,e!==0||(e=window.event,e=e===void 0?16:hu(e.type)),e)}
```

--------------------------------

### Deploy to Render

Source: https://context7.com/livesession/xyd/llms.txt

Render configuration file (render.yaml) for static site deployment, specifying build command and publish path.

```yaml
# Render — render.yaml
services:
- type: web
  name: my-docs
  env: static
  buildCommand: bunx xyd-js build
  staticPublishPath: .xyd/build/client
```

--------------------------------

### Authenticate Outgoing Requests

Source: https://github.com/livesession/xyd/blob/master/packages/xyd-mcp-server/README.md

Example of how to pass a bearer token in the Authorization header for authenticated outgoing requests initiated by tools.

```http
Authorization: Bearer <your-api-token>
```