### Install Renoun Package

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

Command to install the renoun package. This is the first step in setting up renoun in a project.

```bash
npm install "renoun"
```

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

### MDX Content Example

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

Example of an MDX file with exported metadata and React component content. The metadata includes title, description, date, and tags.

```mdx
export const metadata = {
  title: 'Build a Button Component in React',
  description: `Learn how to build a reusable Button component in React that can be used across your application.`, 
  date: '2025-06-07',
  tags: ['react', 'design systems'],
}

In modern web development, creating reusable UI components is a must for efficiency and scalability. React, with its component-based architecture, allows developers to build encapsulated components that manage their own state and can be reused throughout applications.

## Building the Button Component

Let's start by creating our Button component:

```tsx
import React from 'react'

export function Button({ label, onClick, className }) {
  return (
    <button className={className} onClick={onClick}>
      {label}
    </button>
  )
}
```
```

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

### Install Renoun: Automated Project Setup

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/README.md

This command initializes a new Renoun project or adds it to an existing one by prompting the user to select an example to install. It uses npx to run the latest version of the create-renoun package.

```bash
npx create-renoun@latest
```

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

### Displaying Blog Post Content with Validated Metadata

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

This comprehensive example integrates previous snippets to fetch a blog post by slug, retrieve its validated metadata and default export (content), and render the title, summary, and the content within a Next.js page component.

```tsx
import { Directory, withSchema } from 'renoun'
import { z } from 'zod'

export const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
  loader: {
    mdx: withSchema(
      {
        metadata: {
          title: z.string(),
          date: z.coerce.date(),
          summary: z.string().optional(),
          tags: z.array(z.string()).optional(),
        },
      },
      (path) => import(`./posts/${path}.mdx`)
    ),
  },
})

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const slug = (await params).slug
  const post = await posts.getFile(slug, 'mdx')
  const metadata = await post.getExportValue('metadata')
  const Content = await post.getExportValue('default')

  return (
    <>
      <h1>{metadata.title.toString()}</h1>
      <p>{metadata.summary.toString()}</p>
      <Content />
    </>
  )
}
```

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

### Documenting Module Exports with Renoun Reference Component

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

This example shows how to use the Renoun Reference component directly in an MDX file to document exports from a specified source file, providing a structured way to display API information.

```mdx
import { Reference } from 'renoun'

<Reference source="components/Card.tsx" />
```

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

### Generate Blog Post Links with Renoun Directory

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

This snippet shows how to use Renoun's Directory class to get entries from a 'posts' directory, filter them by '.mdx' extension, and generate navigation links for each post using Next.js Link component.

```tsx
import { Directory } from 'renoun'
import Link from 'next/link'

const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
  loader: {
    mdx: (path) => import(`@/posts/${path}.mdx`),
  },
})

export default async function Page() {
  const allPosts = await posts.getEntries()

  return (
    <>
      <h1>Blog</h1>
      <ul>
        {allPosts.map((post) => {
          const pathname = post.getPathname()

          return (
            <li key={pathname}>
              <Link href={pathname}>{post.getTitle()}</Link>
            </li>
          )
        })}
      </ul>
    </>
  )
}
```

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

### Create Renoun Blog Example with npx

Source: https://github.com/souporserious/renoun/blob/main/apps/site/README.md

This command uses the `create-renoun` CLI with `npx` to initialize a new blog project based on this example. It ensures you have the necessary boilerplate code to start building your Renoun and Next.js blog.

```bash
npx create-renoun --example blog
```

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

### Query MDX Files with Renoun Directory

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

Using the renoun Directory class to query all MDX files within a specified path. This allows for easy access to file content and metadata.

```typescript
import { Directory } from 'renoun'

const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
})
```

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

### Render MDX Content Dynamically with Renoun

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

Dynamically renders MDX content based on a URL slug. It fetches an MDX file using `getFile` and renders its default export.

```typescript
import { Directory } from 'renoun'

const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
})

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const slug = (await params).slug
  const post = await posts.getFile(slug, 'mdx')
  const Content = await post.getExportValue('default')

  return <Content />
}
```

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

### Manually Start Renoun WebSocket Server

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/02.next.mdx

Demonstrates how to manually start the renoun WebSocket server using the `createServer` function. This is an alternative to using the CLI for development and production builds.

```javascript
import { createServer } from 'renoun/server'

const server = await createServer()
```

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

### Configure MDX Loader for Renoun Directory

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

Configures a custom loader for MDX files within the renoun Directory class using dynamic import. This is recommended for bundlers like Webpack or Vite.

```typescript
import { Directory } from 'renoun'

const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
  loader: {
    mdx: (path) => import(`./posts/${path}.mdx`),
  },
})
```

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

### Install Renoun: Manual Package Installation

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/README.md

This command installs the Renoun package into your project using npm. After installation, you can begin creating content with your preferred React framework.

```bash
npm install renown
```

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

### Validate MDX Export Metadata with Renoun and Zod

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

This example demonstrates how to use Renoun's withSchema utility along with Zod to define and validate a metadata schema for MDX files. It ensures that each post has a 'metadata' export conforming to the specified structure.

```tsx
import { Directory, withSchema } from 'renoun'
import { z } from 'zod'

export const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
  loader: {
    mdx: withSchema(
      {
        metadata: {
          title: z.string(),
          date: z.coerce.date(),
          summary: z.string().optional(),
          tags: z.array(z.string()).optional(),
        },
      },
      (path) => import(`./posts/${path}.mdx`)
    ),
  },
})
```

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

### Accessing Validated Exported Metadata from MDX Files

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/02.getting-started.mdx

This snippet shows how to retrieve and use the validated 'metadata' export from an MDX file using Renoun's getFile and getExportValue methods after defining a schema with withSchema.

```tsx
import { posts } from './posts.ts'

const post = await posts.getFile('build-a-button-component-in-react.mdx')
const metadata = await post.getExportValue('metadata')
const { title, date, summary, tags } = metadata
```

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

### Configure Additional Languages with Renoun RootProvider

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Demonstrates how to configure additional languages like Python, Rust, and Go using the 'languages' prop within the RootProvider component after installing the 'tm-grammars' package.

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider languages={['python', 'rust', 'go']}>
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

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

### Configure RootProvider for Syntax Highlighting

Source: https://github.com/souporserious/renoun/blob/main/examples/blog/posts/rich-code-examples-with-renoun.mdx

Configure the RootProvider with desired themes and languages for consistent syntax highlighting across all code snippets. This setup is done once in the RootProvider to ensure all fenced code blocks inherit the same presentation without additional configuration.

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider theme="nord" languages={['css', 'tsx', 'typescript']}>
      <html lang="en">
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

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

### Install Dependencies for Vite with Renoun

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/03.vite.mdx

Installs the necessary packages for integrating renoun with Vite, including React, React Server Components, and MDX plugins. Ensure you have a Vite project initialized before running this command.

```bash
npm create vite@latest

<Command variant="install">
  renoun @vitejs/plugin-react @vitejs/plugin-rsc @mdx-js/rollup
</Command>
```

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

### Install @renoun/mdx Package

Source: https://github.com/souporserious/renoun/blob/main/packages/mdx/README.md

Installs the @renoun/mdx package using npm. This is the first step to integrate the MDX plugins into your project.

```bash
npm install @renoun/mdx
```

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

### Metadata Configuration in JavaScript

Source: https://github.com/souporserious/renoun/blob/main/examples/docs/docs/faq.mdx

Defines metadata for a page, including title, summary, and order. This is a common pattern for organizing content in documentation sites.

```javascript
export const metadata = {
  title: 'FAQ',
  summary: 'Frequently asked questions about the docs example.',
  order: 6,
}
```

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

### Start Waku Server with Renoun

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/04.waku.mdx

Execute the 'dev' script to start your Waku server with renoun integrated. This command utilizes the configured scripts in package.json to launch the development server with renoun's full functionality.

```bash
npm run dev
```

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

### Example of Renoun CodeBlock Component Usage

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/02.next.mdx

Illustrates how a Markdown code fence with specific props (allowErrors, shouldFormat) is transformed into Renoun's `CodeBlock` component, rendering the enclosed code.

```jsx
<CodeBlock allowErrors shouldFormat={false}>
  {`const a = 1\nconst b = a + '2'`}
</CodeBlock>
```

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

### Importing Components in JavaScript/TypeScript

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/01.introduction.mdx

Demonstrates how to import the Examples and Socials components from local modules. This is a standard ES module import statement, commonly used in modern JavaScript projects.

```javascript
import { Examples } from './Examples'
import { Socials } from './Socials'
```

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

### Clone renoun Repository

Source: https://github.com/souporserious/renoun/blob/main/CONTRIBUTING.md

This command clones the renoun repository from GitHub to your local machine, allowing you to start making changes. Ensure you have Git installed and configured.

```bash
git clone https://github.com/souporserious/renoun.git
```

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

### Configure Multiple Themes with Renoun RootProvider

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Sets up multiple themes for the application using the RootProvider component. The first theme defined in the object becomes the default. This example demonstrates configuring 'vitesse-light' and 'vitesse-dark' themes.

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      theme={{
        light: 'vitesse-light',
        dark: 'vitesse-dark',
      }}>
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

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

### Install Renoun and ts-morph for Next.js Projects

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/02.next.mdx

Installs the necessary renoun and ts-morph packages for Next.js projects. ts-morph is a core dependency for renoun's code analysis capabilities.

```bash
npm install "renoun" "ts-morph"
```

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

### Add Additional Languages with tm-grammars Package

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Enables support for additional programming languages by installing the optional 'tm-grammars' package and listing the desired languages in the 'languages' prop of RootProvider. This expands the syntax highlighting capabilities beyond the default set.

```bash
npm install --save-dev tm-grammars
```

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

### Configure MDX with Renoun Plugins in Next.js

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/02.next.mdx

Sets up MDX support in Next.js by installing `@next/mdx` and configuring `next.config.mjs`. It includes optional integration of renoun's pre-configured `remarkPlugins` and `rehypePlugins`.

```javascript
import createMDXPlugin from '@next/mdx'
import { remarkPlugins, rehypePlugins } from 'renoun'

const withMDX = createMDXPlugin({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins,
    rehypePlugins,
  },
})

export default withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
})
```

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

### Install Renoun Package

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/04.waku.mdx

Install the renoun package using npm. This command adds renoun as a dependency to your Waku project, making its utilities available for integration.

```bash
npm install
renoun
```

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

### Use Predefined Theme with RootProvider (React)

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Configures renoun to use a predefined theme by name via the `theme` prop in the `RootProvider` component. Requires the `tm-themes` package to be installed.

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider theme="nord">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

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

### Package Export Introspection with Renoun

Source: https://context7.com/souporserious/renoun/llms.txt

Discover and analyze workspace packages or node_modules installations with full export/import resolution using Renoun's Package class. This example demonstrates how to load a package, retrieve specific exports, analyze their metadata (type, value, description), and list all available exports.

```typescript
import { Package } from 'renoun'

const renounMdx = new Package({
  name: '@renoun/mdx',
  loader: {
    'remark/add-headings': () => import('@renoun/mdx/remark/add-headings'),
    'rehype/add-live-code': () => import('@renoun/mdx/rehype/add-live-code'),
  },
})

export default async function PackageDocumentation() {
  // Get package export
  const remarkAddHeadings = await renounMdx.getExport('remark/add-headings')
  const defaultExport = await remarkAddHeadings.getExport('default')

  // Analyze export metadata
  const type = await defaultExport.getType()
  const value = await defaultExport.getValue()
  const description = type.getText()

  // Get all package exports
  const allExports = await renounMdx.getExports()

  return (
    <article>
      <h1>{renounMdx.getName()}</h1>
      <section>
        <h2>Exports</h2>
        <ul>
          {allExports.map((exp) => (
            <li key={exp.getName()}>
              <code>{exp.getName()}</code>
              <pre>{exp.getType()?.getText()}</pre>
            </li>
          ))}
        </ul>
      </section>
    </article>
  )
}
```

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

### Accordion Component Usage in JSX

Source: https://github.com/souporserious/renoun/blob/main/examples/docs/docs/faq.mdx

Demonstrates the usage of an Accordion component, likely for displaying collapsible content. This pattern is useful for FAQs and detailed explanations.

```jsx
<Accordion title="What is this example?">
  A simple documentation site using renoun, Next.js, and Tailwind CSS. It
  demonstrates how to create a modern documentation site with features like
  sidebar navigation, MDX support, and interactive components.
</Accordion>
```

```jsx
<Accordion title="How do I add new docs?">
  Add new `.mdx` files to the `docs/` directory with the required metadata at
  the top. Each file should export a metadata object with title, date, and
  summary fields. The sidebar navigation will be automatically generated based
  on your file structure.
</Accordion>
```

```jsx
<Accordion title="What features are included?">
  
  This example includes: 
  
  - MDX support for rich content
  - Automatic sidebar
  navigation
  - Dark mode support
  - Responsive design
  - Interactive components
  like accordions
  - Code syntax highlighting
  - Last updated timestamps

</Accordion>
```

```jsx
<Accordion title="How do I customize the theme?">
  The theme can be customized through Tailwind CSS configuration. You can modify
  colors, typography, spacing, and other design tokens in the
  `tailwind.config.js` file. The example uses a clean, modern design that's easy
  to extend.
</Accordion>
```

```jsx
<Accordion title="Can I use custom components in MDX?">
  Yes! You can use any React component in your MDX files. The example includes
  several built-in components like Accordion, CodeBlock, and CodeInline. You can
  also create your own components and use them in your documentation.
</Accordion>
```

```jsx
<Accordion title="How do I deploy this site?">
  Since this is a Next.js application, you can deploy it to any platform that
  supports Next.js, such as Vercel, Netlify, or your own hosting solution. The
  example includes all necessary configuration for production deployment.
</Accordion>
```

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

### Configure npm Scripts with Renoun CLI

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/04.cli.mdx

Example of updating package.json scripts to prepend 'renoun' to framework commands. This ensures Renoun manages the framework processes and stays connected to content.

```json
{
  "scripts": {
    "dev": "renoun next dev",
    "build": "renoun next build"
  }
}
```

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

### Configure Renoun with RootProvider (React)

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Sets up the `RootProvider` component at the root of your React application to provide renoun's configuration. It requires wrapping the `html` element and accepts props like `git`, `siteUrl`, and `theme`.

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      git="souporserious/renoun"
      siteUrl="https://renoun.dev"
      theme="theme.json"
    >
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

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

### Workspace Path Resolution with Renoun Directory

Source: https://context7.com/souporserious/renoun/llms.txt

Reference files across monorepo workspaces using the `workspace:` scheme for consistent path resolution. Renoun's Directory class with the 'workspace:' prefix allows referencing files from the monorepo root or other packages, regardless of the current package's location. Examples include referencing examples, shared components, and public assets.

```typescript
import { Directory } from 'renoun'

// From nested package (apps/docs), reference workspace root
const examples = new Directory({
  path: 'workspace:examples', // Resolves to ../../examples
  filter: '**/*.tsx',
})

const sharedComponents = new Directory({
  path: 'workspace:packages/ui/src', // Resolves to ../../packages/ui/src
  loader: {
    tsx: (path) => import(`../../packages/ui/src/${path}.tsx`),
  },
})

// Reference public assets from workspace root
const assets = new Directory({
  path: 'workspace:public',
})

export default async function ExamplesPage() {
  const exampleFiles = await examples.getEntries({ recursive: true })

  return (
    <div>
      <h1>Component Examples</h1>
      <ul>
        {exampleFiles.map((file) => (
          <li key={file.getPathname()}>
            <a href={file.getPathname()}>{file.getName()}</a>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

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

### Enable Git Links and Canonical URLs with Renoun RootProvider

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Set the 'git' prop on the RootProvider to enable edit/source links and canonical URLs. This can be done using a full configuration object or a shorthand string.

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      git={{
        source: 'https://github.com/souporserious/renoun',
        branch: 'main',
        host: 'github',
        owner: 'souporserious',
        repository: 'renoun',
        baseUrl: 'https://github.com',
      }}>
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider git="souporserious/renoun">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider git="pierre:souporserious/renoun@docs">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

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

### Display Code Snippet with File Path Hint

Source: https://github.com/souporserious/renoun/blob/main/examples/blog/posts/rich-code-examples-with-renoun.mdx

Display a code snippet with an optional file path hint. The 'path' attribute in the code fence specifies the file location, which renoun renders above the toolbar for reader context.

```tsx
export function Hero() {
  return (
    <section className="Hero">
      <h1>Build content-rich Next.js sites</h1>
      <p>renoun keeps your markdown organized and your UI expressive.</p>
    </section>
  )
}
```

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

### Automatic Site Navigation with Renoun Components

Source: https://context7.com/souporserious/renoun/llms.txt

Generate navigation structures from directory collections with automatic active state and hierarchy management using Renoun's Navigation component. This example shows how to create a sidebar navigation for documentation, with custom list and item rendering, and active state highlighting.

```typescript
import { Navigation } from 'renoun/components'
import { docs } from './collections'

export default async function DocsLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="docs-layout">
      <aside className="sidebar">
        <Navigation
          collection={docs}
          recursive={true}
          components={{
            List: ({ children }) => <ul className="nav-list">{children}</ul>,
            Item: ({ children, file, isActive }) => (
              <li className={isActive ? 'active' : ''}>
                <a href={file.getPathname()}>{children}</a>
              </li>
            ),
          }}
        />
      </aside>

      <main className="content">
        {children}
      </main>
    </div>
  )
}
```

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

### In-Memory File System for Testing with Renoun

Source: https://context7.com/souporserious/renoun/llms.txt

Create in-memory file systems for testing, server-side rendering, or working with virtual files without disk access using Renoun's MemoryFileSystem. This example shows how to instantiate a MemoryFileSystem and populate it with virtual files, such as markdown content with frontmatter.

```typescript
import { Directory, MemoryFileSystem } from 'renoun'

// Create virtual file system for testing
const memoryFs = new MemoryFileSystem({
  'posts/hello-world.mdx': `---
title: Hello World
date: 2024-01-01
---


```

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

### Define Tutorial Directory with MDX Schema

Source: https://github.com/souporserious/renoun/blob/main/examples/blog/posts/structuring-content-with-renoun-directories.mdx

This TypeScript snippet demonstrates how to define a 'tutorials' directory using Renoun. It specifies the path, filters for '.mdx' files, and configures an MDX loader with a Zod schema for frontmatter validation, including title, date, and duration. The loader imports the MDX content dynamically.

```typescript
import { Directory, withSchema } from 'renoun'
import { z } from 'zod'

const tutorials = new Directory({
  path: 'tutorials',
  filter: '*.mdx',
  loader: {
    mdx: withSchema(
      {
        frontmatter: z.object({
          title: z.string(),
          date: z.coerce.date(),
          duration: z.string(),
        }),
      },
      (path) => import(`./tutorials/${path}.mdx`)
    ),
  },
})
```

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

### Inspect Package Exports and Imports

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/src/file-system/README.mdx

Demonstrates using the `Package` helper to discover workspace packages, resolve `node_modules` installations, or fall back to `GitHostFileSystem`. It analyzes package manifests to allow introspection of exports and imports without manual file traversal.

```typescript
import { Package } from 'renoun'

const renounMdx = new Package({
  name: '@renoun/mdx',
  loader: {
    'remark/add-headings': () => import('@renoun/mdx/remark/add-headings'),
  },
})
const remarkAddHeadings = await renounMdx.getExport('remark/add-headings')
const defaultExport = await remarkAddHeadings.getExport('default')

await defaultExport.getType()
await defaultExport.getValue()
```

```typescript
import { Package } from 'renoun'

const renounMdx = new Package({
  name: '@renoun/mdx',
  loader: {
    'remark/add-headings': () => import('@renoun/mdx/remark/add-headings'),
  },
})
const remarkAddHeadings = await renounMdx.getExport('remark/add-headings')
const defaultExport = await remarkAddHeadings.getExport('default')
const type = await defaultExport.getType()
const value = await defaultExport.getValue()
```

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

### CodeBlock - Syntax Highlighting Component

Source: https://context7.com/souporserious/renoun/llms.txt

This component renders syntax-highlighted code blocks with features like line numbers, quick info on hover, and token-level highlighting using TextMate grammars.

```APIDOC
## CodeBlock - Syntax Highlighting Component

### Description
Renders syntax-highlighted code blocks with line numbers, quick info on hover, and token-level highlighting using TextMate grammars.

### Method
N/A (This is a React component.)

### Endpoint
N/A

### Parameters

#### Props
- **language** (string) - Required - The programming language of the code (e.g., 'typescript', 'javascript').
- **value** (string) - Required - The code content to display.
- **showLineNumbers** (boolean) - Optional - Whether to display line numbers.
- **highlightedLines** (string) - Optional - A string specifying which lines to highlight (e.g., '2-4', '5').
- **toolbar** (object) - Optional - Configuration for the code block toolbar.
  - **showCopy** (boolean) - Optional - Whether to show the copy button.
  - **showLanguage** (boolean) - Optional - Whether to show the language name.

### Request Example
```typescript
import { CodeBlock } from 'renoun/components'

export default function DocumentationPage() {
  const codeExample = `
function fibonacci(n: number): number {
  if (n <= 1) return n
  return fibonacci(n - 1) + fibonacci(n - 2)
}

const result = fibonacci(10)
console.log(result)
  `.trim()

  return (
    <main>
      <h1>Algorithm Examples</h1>

      <CodeBlock
        language="typescript"
        value={codeExample}
        showLineNumbers
        highlightedLines="2-4"
        toolbar={{
          showCopy: true,
          showLanguage: true,
        }}
      />

      {/* Inline code highlighting */}
      <p>
        Use the <code>fibonacci</code> function to calculate sequences.
      </p>
    </main>
  )
}
```

### Response
N/A (This is a UI component.)

### Response Example
N/A
```

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

### Validate MDX Headings Export with Valibot in TypeScript

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/06.valibot.mdx

This example shows how to use Valibot to validate the 'headings' export from MDX files, ensuring type safety. It manually types the exported headings in the schema to work with TypeScript's inference.

```typescript
import { Directory, withSchema } from 'renoun'
import * as v from 'valibot'

const headingsSchema = v.array(
  v.object({
    depth: v.picklist([1, 2, 3, 4, 5, 6]),
    text: v.string()
  })
)

const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
  loader: {
    mdx: withSchema(
      {
        frontmatter: frontmatterSchema,
        headings: headingsSchema
      },
      (path) => import(`./posts/${path}.mdx`)
    )
  }
})
```

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

### Exclude Files from Dynamic Imports with Webpack

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/02.next.mdx

This example shows how to use Webpack-specific magic comments (`webpackExclude`) within a dynamic import to prevent certain files, like those in `node_modules`, from being included in the bundle. This optimizes bundle size for dynamic imports.

```tsx
import { Directory } from 'renoun'

const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
  loader: {
    mdx: (path) => {
      return import(
        /* webpackExclude: /node_modules/ */
        `@/posts/${path}.mdx`
      )
    },
  },
})
```

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

### Create and Query File System Directory Collection in TypeScript

Source: https://context7.com/souporserious/renoun/llms.txt

Demonstrates how to create a queryable file system collection using renoun's Directory class. It includes schema validation with Zod for frontmatter and custom loaders for MDX files. The snippet shows how to fetch entries and access validated frontmatter for rendering.

```typescript
import { Directory, withSchema } from 'renoun'
import { z } from 'zod'

// Create a basic directory collection
const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
  basePathname: null,
  loader: {
    mdx: withSchema(
      {
        frontmatter: z.object({
          title: z.string(),
          date: z.coerce.date(),
          summary: z.string().optional(),
          tags: z.array(z.string()).optional(),
        }),
      },
      (path) => import(`./posts/${path}.mdx`)
    ),
  },
  sort: 'frontmatter.date',
})

// Query entries and access validated exports
export default async function BlogIndex() {
  const allPosts = await posts.getEntries()

  return (
    <ul>
      {allPosts.map(async (post) => {
        const pathname = post.getPathname()
        const frontmatter = await post.getExportValue('frontmatter')

        return (
          <li key={pathname}>
            <a href={pathname}>{frontmatter.title}</a>
            <time>{frontmatter.date.toLocaleDateString()}</time>
          </li>
        )
      })}
    </ul>
  )
}
```

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

### Render MDX File Contents Dynamically

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/02.next.mdx

This example shows how to use a Directory instance to load and render the contents of dynamically imported TSX components. It fetches file exports and displays their names and descriptions, suitable for dynamic component loading.

```tsx
import { Directory } from 'renoun'

const components = new Directory({
  path: 'components',
  filter: '*.tsx',
  loader: {
    tsx: (path) => import(`@/components/${path}.tsx`),
  },
})

export default async function Page(props: PageProps<'/components/[...slug]'>) {
  const { slug } = await props.params
  const component = await components.getFile(slug, 'tsx')
  const fileExports = await component.getExports()

  return fileExports.map((fileExport) => {
    return (
      <div key={fileExport.getName()}>
        <h2>{fileExport.getName()}</h2>
        <p>{fileExport.getDescription()}</p>
      </div>
    )
  })
}
```

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

### Include Specific Files in Dynamic Imports with Webpack

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/02.next.mdx

This snippet demonstrates using Webpack magic comments (`webpackInclude`) to specifically include files that match a given regular expression, such as example files, in dynamic imports. This allows for targeted inclusion of code modules.

```tsx
function getComponentExample(path: string) {
  return import(
    /* webpackInclude: /(?:\.examples|\/examples\/).*\.tsx?$/ */
    `@/components/${path}.tsx`
  )
}
```

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

### File Selection Priority Examples - TypeScript

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/src/file-system/README.mdx

Illustrates Renoun's file selection logic. It demonstrates how sibling files are preferred over directories with the same name, and base files are preferred over files with modifiers when querying file system entries.

```tsx
import { Directory, MemoryFileSystem } from 'renoun'

const directory = new Directory({ path: 'posts' })

// When both integrations.mdx and integrations/ exist
// returns integrations.mdx (sibling file, not the directory)
const entry = await directory.getEntry('integrations')

// When both Reference.tsx and Reference.examples.tsx exist
// returns Reference.tsx (base file without modifier)
const file = await directory.getFile('Reference')
```

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

### Initialize Directory Instance with Loader - TypeScript

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/src/file-system/README.mdx

Instantiates a `Directory` object to target a set of files and directories. It specifies a path and a loader for the `mdx` file extension, which will be used to load file contents via a bundler.

```tsx
import { Directory } from 'renoun'

const posts = new Directory({
  path: 'posts',
  loader: {
    mdx: (path) => import(`./posts/${path}.mdx`),
  },
})
```

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

### Generate Blog Index with Schematized Loader - TypeScript

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/src/file-system/README.mdx

Generates a list of blog posts by querying `mdx` files within a directory. It uses `getEntries` to retrieve all matching entries, filters them by `*.mdx` extension, and applies a schema (`PostType`) to the loader for typed frontmatter access.

```tsx
import { Directory, withSchema } from 'renoun'

interface PostType {
  frontmatter: {
    title: string
    date: Date
  }
}

const posts = new Directory({
  path: 'posts',
  filter: '*.mdx',
  loader: {
    mdx: withSchema<PostType>((path) => import(`./posts/${path}.mdx`)),
  },
})

export default async function Page() {
  const allPosts = await posts.getEntries()

  return (
    <>
      <h1>Blog</h1>
      <ul>
        {allPosts.map(async (post) => {
          const pathname = post.getPathname()
          const frontmatter = await post.getExportValue('frontmatter')

          return (
            <li key={pathname}>
              <a href={pathname}>{frontmatter.title}</a>
            </li>
          )
        })}
      </ul>
    </>
  )
}
```

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

### Client-Side Script Function Example (TS)

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/src/components/Script.mdx

An example of a client-side script intended to be imported by the Renoun Script component. It defines a global type for window and exports a default function that interacts with the DOM.

```ts
// use types if you want
declare global {
  interface Window {
    __TableOfContents__: {
      register: (headingIds: string[]) => void
    }
  }
}

// default export MUST be a function
export default function () {
  // use client APIs
  const headingIds = document.querySelectorAll('a[href^="#"]').forEach((a) => {
    // ...
  })
  window.__TableOfContents__ = {
    register: (ids) => {
      //   ...
    },
  }
}
```

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

### Reading MDX Files with Frontmatter

Source: https://context7.com/souporserious/renoun/llms.txt

Demonstrates how to read MDX files from a specified directory using Renoun's Directory class. It shows how to get all entries, retrieve a specific file by name and extension, and extract exported values like frontmatter.

```typescript
import { Directory } from 'renoun'
import { memoryFs } from '@zenfs/memory'

const testPosts = new Directory({
  path: 'posts',
  fileSystem: memoryFs,
  filter: '*.mdx',
})

export async function testBlogPosts() {
  const posts = await testPosts.getEntries()
  console.assert(posts.length === 2, 'Should have 2 posts')

  const firstPost = await testPosts.getFile('hello-world', 'mdx')
  const frontmatter = await firstPost.getExportValue('frontmatter')
  console.assert(frontmatter.title === 'Hello World', 'Title should match')

  return posts
}
```

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

### Configure Development Server Script for Renoun HMR

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/src/components/Refresh/Refresh.mdx

This JSON snippet shows the `scripts` section of a `package.json` file, specifically configuring the `dev` script to use `renoun next dev`. This command is essential for running the development server with hot module replacement enabled via Renoun.

```json
{
  "scripts": {
    "dev": "renoun next dev"
  }
}
```

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

### Enable Renoun Debug Logging with Environment Variable

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Enable internal debug logging for the Renoun CLI, WebSocket server, and other utilities by setting the RENOUN_DEBUG environment variable. This is useful for troubleshooting issues.

```bash
# Most verbose logging
RENOUN_DEBUG=true renoun next dev
```

```bash
# Only info and above
RENOUN_DEBUG=info renoun next dev
```

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

### Set Site URL for Absolute URLs with Renoun RootProvider

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Provide a 'siteUrl' prop to the RootProvider to ensure that sitemaps and other absolute URLs are generated correctly. This is essential for SEO and proper link resolution.

```tsx
import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider siteUrl="https://renoun.dev">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}
```

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

### Integrating Git Metadata for Documentation Pages

Source: https://context7.com/souporserious/renoun/llms.txt

Shows how to use Renoun's Directory and File classes to fetch Git metadata for documentation files. This includes last commit date, first commit date, authors, and generating URLs for viewing source, history, and blame information.

```typescript
import { Directory } from 'renoun'

const docs = new Directory({
  path: 'docs',
  filter: '**/*.mdx',
})

export default async function DocumentPage({ params }: { params: { slug: string } }) {
  const doc = await docs.getFile(params.slug, 'mdx')
  const Content = await doc.getExportValue('default')

  const lastCommitDate = await doc.getLastCommitDate()
  const firstCommitDate = await doc.getFirstCommitDate()
  const authors = await doc.getAuthors()

  const sourceUrl = doc.getSourceUrl({ repository: 'owner/repo', ref: 'main' })
  const editUrl = doc.getEditUrl({ repository: 'owner/repo' })
  const historyUrl = doc.getHistoryUrl({ repository: 'owner/repo' })
  const blameUrl = doc.getBlameUrl({ repository: 'owner/repo' })

  return (
    <article>
      <header>
        <Content />
      </header>

      <footer className="doc-footer">
        <div>
          Created: {firstCommitDate?.toLocaleDateString()}<br />
          Last updated: {lastCommitDate?.toLocaleDateString()}
        </div>

        <div>
          Contributors: {authors?.map(a => a.name).join(', ')}
        </div>

        <nav>
          <a href={editUrl}>Edit this page</a>
          <a href={sourceUrl}>View source</a>
          <a href={historyUrl}>View history</a>
          <a href={blameUrl}>View blame</a>
        </nav>
      </footer>
    </article>
  )
}
```

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

### Set Default Theme with data-theme Attribute

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Specifies a default theme by adding a 'data-theme' attribute to the html element. This allows for explicit control over which theme is applied initially when multiple themes are configured.

```html
<html data-theme="dark">
  ...
</html>
```

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

### Configure Webpack for ESM Support in Next.js

Source: https://github.com/souporserious/renoun/blob/main/apps/site/guides/02.next.mdx

Adjusts the Webpack configuration in next.config.mjs to set up `resolve.alias` for ESM file support. This is crucial for importing renoun components and utilities without errors.

```javascript
export default {
  webpack(config) {
    config.resolve.extensionAlias = {
      '.js': ['.ts', '.tsx', '.js'],
    }
    return config
  },
}
```

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

### Avoid Git Rate Limits with Access Token

Source: https://github.com/souporserious/renoun/blob/main/packages/renoun/src/file-system/README.mdx

Explains how to provide an access token to `GitHostFileSystem` to bypass strict anonymous rate limits imposed by Git providers like GitHub, GitLab, and Bitbucket. Using a token enables more efficient metadata access and reduces request volume.

```typescript
import { GitHostFileSystem } from 'renoun'

const repoFs = new GitHostFileSystem({
  repository: 'souporserious/renoun',
  token: process.env.GITHUB_TOKEN,
})
```

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

### Remote Git Repository Access with Renoun GitHostFileSystem

Source: https://context7.com/souporserious/renoun/llms.txt

Illustrates using Renoun's `GitHostFileSystem` to access files from remote Git repositories like GitHub, GitLab, and Bitbucket. It includes features like in-memory caching and streaming.

```typescript
import { Directory, GitHostFileSystem } from 'renoun'

// Create file system adapter for remote repository
const repoFs = new GitHostFileSystem({
  repository: 'souporserious/renoun',
  ref: 'main',
  token: process.env.GITHUB_TOKEN, // Avoids rate limits
  filter: (path) => path.includes('docs/'),
})

// Query remote files as if they were local
const remoteDocs = new Directory({
  path: '.',
  fileSystem: repoFs,
  filter: '**/*.mdx',
})

export default async function RemoteDocsPage({ params }: { params: { slug: string } }) {
  const doc = await remoteDocs.getFile(params.slug, 'mdx')
  const Content = await doc.getExportValue('default')
  const sourceUrl = doc.getSourceUrl({ repository: 'souporserious/renoun' })

  return (
    <main>
      <Content />
      <a href={sourceUrl} target="_blank">View source on GitHub</a>
    </main>
  )
}

```

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

### Disable Renoun Theme Script with RootProvider

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Allows disabling Renoun's built-in theme management script by setting 'includeThemeScript' to false in the RootProvider. This is useful when integrating with other theming solutions to prevent conflicts.

```tsx
import { RootProvider } from 'renoun'
import { ThemeProvider } from 'next-themes'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      theme={{ light: 'nord', dark: 'nord' }}
      includeThemeScript={false}>
      <html>
        <body>
          <ThemeProvider>{children}</ThemeProvider>
        </body>
      </html>
    </RootProvider>
  )
}
```

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

### Customize Image Output Directory with RootProvider (React)

Source: https://github.com/souporserious/renoun/blob/main/apps/site/docs/03.configuration.mdx

Configures the `images.outputDirectory` option within the `RootProvider` component to specify a custom cache path for Figma images. This path should be accessible as static assets by your framework.

```tsx
<RootProvider images={{ outputDirectory: 'public/design-assets' }} />
```