Documenting

Overview

Better Auth uses Fumadocs with MDX for documentation. This page explains how to add and update documentation effectively.

Project Structure

Writing Documentation

Creating New Pages

1. Add your MDX file in docs/content/docs/<your_file_name>.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:

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

# 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

Code Blocks

Use language-specific syntax highlighting:

```typescript
import { BetterAuth } from "better-auth";
 
const auth = new BetterAuth({
  // configuration
});
```

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

```typescript title="auth.ts"
import { BetterAuth } from "better-auth";
 
const auth = new BetterAuth({
  // configuration
});
```

You can also highlight specific lines in a codeblock:

```typescript title="auth.ts"
import { BetterAuth } from "better-auth";
 
const auth = new BetterAuth({ // [!codeㅤhighlight]
  // configuration  // [!codeㅤhighlight]
}); // [!codeㅤhighlight]
```

The result:

import { BetterAuth } from "better-auth";
 
const auth = new BetterAuth({
  // configuration
}); 

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

# 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 Discord server 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! 📚