# Customize Documentation

Widgetbook's documentation system is fully customizable through the `docsBuilder` function. 
You can customize documentation at two levels: globally for all components, or individually for specific components.

## Global Customization

### Basic Example

```dart
import 'package:widgetbook/widgetbook.dart';

final config = Config(
  components: components,
  docsBuilder: () => [
    const ComponentNameDocBlock(),
    const PrimaryStoryDocBlock(),
  ],
  addons: [
    // Your addons here
  ],
);
```

## Story Preview Height

By default, story previews in docs are rendered inside a fixed-height container (500px). This ensures widgets that require bounded constraints (e.g. `Scaffold`, `Overlay`, `Expanded`) render correctly.

For simple widgets with a natural intrinsic height (e.g. buttons, cards), you can opt into unconstrained rendering using the `.unconstrained()` constructor:

### Global Unconstrained Rendering

```dart
final config = Config(
  components: components,
  docsBuilder: () => [
    const ComponentNameDocBlock(),
    const DartCommentDocBlock(),
    const StoriesDocBlock.unconstrained(),
  ],
);
```

### Per-Component Override

```dart
// Screen-level component: use a taller fixed height
final component = ComponentMeta(
  docsBuilder: (blocks) => blocks.replaceFirst<StoriesDocBlock>(
    const StoriesDocBlock(height: 800),
  ),
);

const meta = Meta(MyScreen.new);
```

```dart
// Simple widget: use unconstrained rendering
final component = ComponentMeta(
  docsBuilder: (blocks) => blocks.replaceFirst<StoriesDocBlock>(
    const StoriesDocBlock.unconstrained(),
  ),
);

const meta = Meta(MyButton.new);
```

## Component-Level Customization

Override documentation for specific components via the `docsBuilder` parameter in the `ComponentMeta` tag.

### Basic Override

```dart
import 'package:widgetbook/widgetbook.dart';

final component = ComponentMeta(
  docsBuilder: (blocks) => [
    const ComponentNameDocBlock(),
    const TextDocBlock('A custom button component for our app.'),
    const StoriesDocBlock(),
  ],
);

const meta = Meta(MyButton.new);
```

### Modifying Default Blocks

The `docsBuilder` function receives the default blocks list, allowing you to modify it:

```dart
final component = ComponentMeta(
  docsBuilder: (blocks) => blocks.replaceFirst<DartCommentDocBlock>(
    const TextDocBlock('Custom description for this specific component.'),
  ),
);

const meta = Meta(MyButton.new);
```

### Adding Blocks

Add blocks before or after existing ones using extension methods:

```dart
final component = ComponentMeta(
  docsBuilder: (blocks) => blocks
    ..insertAfter<ComponentNameDocBlock>(
      const TextDocBlock('⭐ This is our most popular component!'),
    ),
);

const meta = Meta(MyButton.new);
```

### Complex Customization

Combine multiple modifications:

```dart
final component = ComponentMeta(
  docsBuilder: (blocks) => blocks
    ..insertBefore<DartCommentDocBlock>(
      WidgetDocBlock(
        Image.asset('assets/diagram.png'),
      ),
    )
    ..replaceFirst<StoriesDocBlock>(
      const PrimaryStoryDocBlock(), // Only show primary example
    )
    ..insertAfter<PrimaryStoryDocBlock>(
      const TextDocBlock('For more examples, see our style guide.'),
    ),
);

const meta = Meta(MyComplexWidget.new);
```