---
title: Documenting
description: Documentation Guide for Better Auth
---

## Overview

Better Auth uses [Fumadocs](https://fumadocs.vercel.app/) with MDX for documentation. This page explains how to add and update documentation effectively.

## Project Structure

<Files>
  <Folder name="docs" defaultOpen>
    <Folder name="components" defaultOpen>
      <File name="sidebar-content.tsx" />
    </Folder>
    <Folder name="content" defaultOpen>
      <Folder name="docs" defaultOpen>
        <File name="some_documentation.mdx" />
      </Folder>
    </Folder>
  </Folder>
</Files>

## Writing Documentation

### Creating New Pages

1. Add your MDX file in `docs/content/docs/<your_file_name>.mdx`:

<Callout>
  #### File Name Convention * The file name should be in the format of
  `some-feature.mdx`. (Kebab-case) * The file name represents the URL route to
  that page. For example, if the file name is `some-feature.mdx`, the URL route
  will be `/docs/some-feature`. * Place the file in their respective category
  folder. For example, if the file is in the `guides` category, place it in the
  `/guides` folder.
</Callout>

```mdx
---
title: Your Feature
description: Description of your feature
---

# Your Feature

Introduction to your feature here...
```

2. Update the sidebar in `docs/components/sidebar-content.tsx`:

<Callout>
  To find out what icon you would like to use for the sidebar, you can check out
  the <Link href="https://lucide.dev/icons/">Lucide Icons</Link> library.
</Callout>

```tsx
export const contents: Content[] = {
  items: [
    {
      // Existing items...
    },
    {
      title: "Your Section",
      icon: <SomeLucideIcon className="size-4" />,
      items: [
        {
          title: "Your Feature",
          icon: <OtherLucideIcon className="size-4" />,
          href: "/docs/your-feature",
        },
      ],
    },
  ],
};
```

---

## MDX Guidelines

### Basic Formatting

```mdx
# Main Title

## Section

This is a paragraph with **bold** and _italic_ text.

### Subsection

- List item 1
- List item 2

1. Order list item 1
2. Order list item 2
```

### Components

<Accordions>
    <Accordion title="Callouts">
        ```mdx
        <Callout>Important information goes here</Callout>
        <Callout type="warn">Some warning</Callout>
        <Callout type="info">Some info</Callout>
        <Callout type="error">Some error</Callout>
        ```
        <Callout>Important information goes here</Callout>
        <Callout type="warn">Some warning</Callout>
        <Callout type="info">Some info</Callout>
        <Callout type="error">Some error</Callout>
    </Accordion>
    <Accordion title="Files">
        ```mdx
        <Files>
            <Folder name="docs" defaultOpen>
                <File name="some_documentation.mdx" />
            </Folder>
        </Files>
        ```

        <Files>
            <Folder name="docs" defaultOpen>
                <File name="some_documentation.mdx" />
            </Folder>
        </Files>
    </Accordion>
    <Accordion title="Links">
        ```mdx
        <Link href="/docs/introduction">Link to Introduction</Link>
        ```
        <Link href="/docs/introduction">Link to Introduction</Link>
    </Accordion>
    <Accordion title="Accordions">
        ```mdx
        <Accordions>
            <Accordion title="Accordion 1">
                Some content!
            </Accordion>
            <Accordion title="Accordion 2">
                Some content!
            </Accordion>
        </Accordions>
        ```
        <Accordions>
            <Accordion title="Accordion 1">
                Some content!
            </Accordion>
            <Accordion title="Accordion 2">
                Some content!
            </Accordion>
        </Accordions>
    </Accordion>
    <Accordion title="Steps">
        ```mdx
        <Steps>
            <Step>
                ## Step 1
                Hello world!
            </Step>
            <Step>
                ## Step 2
                Hello world!
            </Step>
        </Steps>
        ```
        <Steps>
            <Step>
                <span className="text-xl font-bold">Step 1</span>
                <span className="block mb-3 mt-2">Hello world!</span>
            </Step>
            <Step>
                <span className="text-xl font-bold">Step 2</span>
                <span className="block mb-3 mt-2">Hello world!</span>
            </Step>
        </Steps>
    </Accordion>
    <Accordion title="Tabs">
        ```mdx
        <Tabs items={['Javascript', 'Rust']}>
            <Tab value="Javascript">Javascript is weird</Tab>
            <Tab value="Rust">Rust is fast</Tab>
        </Tabs>
        ```
        <Tabs items={['Javascript', 'Rust']}>
            <Tab value="Javascript">Javascript is weird</Tab>
            <Tab value="Rust">Rust is fast</Tab>
        </Tabs>
    </Accordion>

</Accordions>

### Code Blocks

Use language-specific syntax highlighting:

````mdx
```typescript
import { BetterAuth } from "better-auth";

const auth = new BetterAuth({
  // configuration
});
```
````

Optionally, you can also specify a file name for the code block:

````mdx
```typescript title="auth.ts"
import { BetterAuth } from "better-auth";

const auth = new BetterAuth({
  // configuration
});
```
````

You can also highlight specific lines in a codeblock:

````mdx
```typescript title="auth.ts"
import { BetterAuth } from "better-auth";

const auth = new BetterAuth({ // [!codeㅤhighlight]
  // configuration  // [!codeㅤhighlight]
}); // [!codeㅤhighlight]
```
````

The result:

```typescript title="auth.ts"
import { BetterAuth } from "better-auth";

const auth = new BetterAuth({// [!code highlight]
  // configuration  // [!code highlight]
}); // [!code highlight]
```

---

## Best Practices

### Do's

- Keep documentation up-to-date with code changes
- Use clear, concise language
- Include practical examples
- Document error cases and edge conditions
- Use proper headings hierarchy
- Include cross-references to related docs

### Don'ts

- Don't repeat information unnecessarily
- Don't leave outdated examples
- Don't use complex jargon without explanation
- Don't skip documenting breaking changes
- Don't leave TODO comments in published docs

## Local Development

```bash
# Install dependencies
pnpm install

# Start docs development server
pnpm -F docs dev
```

## Document Types

### 1. Guides

- Step-by-step instructions
- Tutorial-style content

### 2. Reference Documentation

- API documentation
- Configuration options
- Type definitions

### 3. Examples

- Code snippets
- Complete examples
- Use cases


## Contributing to Documentation

1. **Find the Right File**

   - Navigate to `docs/content/docs/`
   - Locate the relevant MDX file or create a new one

2. **Make Your Changes**

   - Update or add content
   - Follow the MDX formatting guidelines
   - Include examples where appropriate

3. **Test Locally**

   - Run the development server
   - Check your changes
   - Verify links and navigation

4. **Submit Changes**
   - Create a pull request
   - Include a clear description of documentation changes
   - Request review from documentation maintainers

## Getting Help

Need assistance with documentation?

- Join our <Link href="https://discord.gg/GYC3W7tZzb">Discord server</Link> and ask for help!
- Open an issue with the `documentation` label

Remember: Good documentation is crucial for Better Auth's success. Thank you for helping improve it! 📚
