Blade intelligently keeps your data up-to-date for you, so no extra state management is needed for the output of your read queries. The data is refreshed:

• When a mutation happens (in the same DB transaction as the mutation).
• Every 5 seconds while the window is in focus.
• When the window gains focus.
• When the device was offline and goes back online.

Even the application itself is revalidated. Whenever you deploy a new version of your web app, Blade will detect the drift and synchronize itself between server and client, resolving the new client assets in the browser and replacing the UI with the updated code. This currently happens immediately, but will soon be limited to when the browser window is inactive.

Lastly, even React itself is revalidated. If you upgrade React, Blade will unmount the old React on the client, mount the new React, and then re-mount your application.

MDX (Markdown + JSX) is a powerful way to write content that combines the best of both worlds: Markdown and React. It allows you to write content in a way that is easy to read and write, while also being able to use React components within your content.

MDX provides several benefits for creating rich documentation:

• Familiar syntax: Write content in standard Markdown syntax
• Interactive components: Embed React components directly in your content
• Dynamic content: Create interactive documentation and tutorials
• Rich experiences: Build engaging, dynamic content experiences
• Type safety: Full TypeScript support for components and props

Using MDX in blade is straightforward - simply create a new file with the .mdx extension. You can then write markdown and embed React components within your content.

---
title: Hello World
---

# Hello World

Welcome to your first MDX page! You can use **bold text**, *italic text*, and even [links](https://example.com).

<button className="px-4 py-2 bg-blue-500 text-white rounded">
  Click me
</button>

You can use any React component in your MDX files.

import { Button } from '@/components/button';

<Button>Click me</Button>

MDX automatically converts markdown primitives like # into HTML elements like h1. You can style these with CSS, or enhance them by exporting a components object from your layout.tsx to customize their rendering.

For example, to add anchor links to all headings:

import { Heading } from '@/components/heading';

export const components = {
  h1: (props: HeadingProps) => (
    <Heading
      level={1}
      {...props}
      className="scroll-mt-20"
    />
  ),
  h2: (props: HeadingProps) => (
    <Heading
      level={2}
      {...props}
      className="scroll-mt-16"
    />
  ),
};

For documentation websites, a table of contents helps users navigate your content. Blade automatically generates a table of contents from your MDX headings and passes it to your layout component.

The table of contents structure:

type TableOfContents = {
  value: string;
  depth: number;
  children?: TableOfContents[];
};

You can use this in your layout to create a sidebar navigation:

const DocsLayout = ({
  children,
  tableOfContents,
}: {
  children: React.ReactNode;
  tableOfContents: TableOfContents[];
}) => {
  return (
    <div className="flex">
      <aside className="w-64 bg-white border-r min-h-screen p-4">
        <nav>
          {tableOfContents.map((item) => (
            <a
              key={item.value}
              href={`#${item.value.toLowerCase().replace(/\s+/g, '-')}`}
              className="block py-1 text-sm text-gray-600 hover:text-gray-900"
            >
              {item.value}
            </a>
          ))}
        </nav>
      </aside>
      
      <main className="flex-1 p-8">
        <div className="prose max-w-none">
          {children}
        </div>
      </main>
    </div>
  );
};

Frontmatter allows you to add metadata to your MDX files. The title field is reserved and automatically sets the page title.

---
title: Getting Started with Blade
---

# Getting Started with Blade

Your content here...

To demonstrate the power of MDX, let's create a simple documentation website. You can see a real-world example in the Blade documentation.

docs/
├── pages/
│   ├── layout.tsx
│   └── index.mdx
└── styles.css

To instantly have nice styling on the MDX pages, we make use of the @tailwindcss/typography plugin, which provides the prose class. This plugin automatically styles your markdown content with beautiful typography defaults.

First, ensure the typography plugin is imported in your CSS file:

@plugin "@tailwindcss/typography";

Then create your layout:

import type { TableOfContents } from '@ronin/blade/types';

const DocsLayout = ({
  children,
  tableOfContents,
}: {
  children: React.ReactNode;
  tableOfContents: TableOfContents[];
}) => {
  return (
    <div className="min-h-screen bg-gray-50">
      <header className="bg-white border-b">
        <div className="max-w-7xl mx-auto px-4 py-4">
          <h1 className="text-2xl font-bold">Documentation</h1>
        </div>
      </header>
      
      <div className="max-w-7xl mx-auto flex">
        <aside className="w-64 bg-white border-r min-h-screen p-4">
          <nav className="space-y-2">
            {tableOfContents.map((item) => (
              <a
                key={item.value}
                href={`#${item.value.toLowerCase().replace(/\s+/g, '-')}`}
                className="block py-1 text-sm text-gray-600 hover:text-gray-900"
              >
                {item.value}
              </a>
            ))}
          </nav>
        </aside>
        
        <main className="flex-1 p-8">
          <article className="prose max-w-none">
            {children}
          </article>
        </main>
      </div>
    </div>
  );
};

export default DocsLayout;

---
title: Getting Started
---

# Getting Started

Welcome to our documentation! This guide will help you get up and running quickly.

## Installation

Install the package using your preferred package manager:

```bash
bunx @ronin/blade init

MDX provides a powerful way to create rich, interactive documentation. By combining the simplicity of Markdown with the flexibility of React components, you can build documentation that's both easy to write and highly engaging for users.

Start with simple components and gradually add more complex interactions as your documentation grows. Remember to maintain consistency in your design system and optimize for performance as your MDX content scales.

For more examples and advanced usage patterns, explore the Blade documentation and examples directory.