# Extending Bengal

URL: /bengal/docs/build-sites/extend/
Section: extend
Description: Create custom directives, content sources, collections, and build hooks

---

> For a complete page index, fetch /bengal/llms.txt.

Need a custom directive, remote source, or build hook? This section covers
Bengal's extension points. Most sites never need this — start with
Authoring (/bengal/docs/build-sites/write/authoring/) and Theming (/bengal/docs/build-sites/customize/) first.

Plugin authors should read Contributor
Quickstart (/bengal/docs/get-started/quickstart-contributor/) for dev setup, then pick an extension type below.

Build Hooks

Run external tools before and after Bengal builds

(/bengal/docs/build-sites/extend/build-hooks/)

Theme Customization

Override templates and customize CSS styling

(/bengal/docs/build-sites/extend/theme-customization/)

Content Collections

Define typed schemas for frontmatter validation and IDE support

(/bengal/docs/build-sites/extend/collections/)

Template Shortcodes

Create template-only embeds without writing Python

(/bengal/docs/build-sites/extend/shortcodes/)

Custom Directives

Create custom MyST directive blocks for specialized content

(/bengal/docs/build-sites/extend/custom-directives/)

Writing Plugins

Create plugins that add directives, template functions, content sources, and build hooks

(/bengal/docs/build-sites/extend/plugins/)

Custom Content Sources

Fetch content from APIs, databases, or remote services

(/bengal/docs/build-sites/extend/custom-sources/)

Create Custom Skeletons

Build reusable site structure templates with skeleton YAML

(/bengal/docs/build-sites/extend/custom-skeletons/)

## Extension Points

Bengal supports several extension mechanisms:

Extension Type
Use Case
Difficulty

Build Hooks (build-hooks/)
Run external tools (Tailwind, esbuild) before/after builds
Easy

Theme Customization (theme-customization/)
Override templates and CSS
Easy

Content Collections (collections/)
Type-safe frontmatter with schema validation
Moderate

Template Shortcodes (shortcodes/)
Add template-only embeds without Python
Easy

Custom Directives (custom-directives/)
Create new MyST directive blocks
Advanced

Custom Content Sources (custom-sources/)
Fetch content from APIs, databases, or remote services
Advanced

## Architecture Overview

Extensions integrate at different stages of the build pipeline:

flowchart TB
subgraph "Pre-Build"
A[Build Hooks]
end

subgraph "Discovery Phase"
B[Content Sources]
C[Collections & Schemas]
end

subgraph "Processing Phase"
D[Custom Directives]
end

subgraph "Rendering Phase"
E[Theme Templates]
F[CSS Customization]
end

subgraph "Post-Build"
G[Build Hooks]
end

A --> B
B --> C
C --> D
D --> E
E --> F
F --> G

## Quick Start Examples

### Build Hooks

Integrate external tools by adding hooks to your`bengal.toml`:

toml
TOML

```
[dev_server]
pre_build = [
    "npx tailwindcss -i src/input.css -o assets/style.css"
]
post_build = [
    "echo 'Build complete!'"
]
```
### Theme Customization

Override any theme template by placing a file with the same name in your project's`templates/`directory:

tree-sitter-query
TREE-SITTER-QUERY

```
your-project/
├── templates/
│   └── page.html      # Overrides theme's page.html
└── bengal.toml
```
### Content Collections

Define typed schemas for your content:

python
PYTHON

```
# collections.py
from dataclasses import dataclass
from datetime import datetime
from bengal.collections import define_collection

@dataclass
class BlogPost:
    title: str
    date: datetime
    author: str = "Anonymous"

collections = {
    "blog": define_collection(schema=BlogPost, directory="content/blog"),
}
```
### Custom Directives

Create new directive blocks by implementing the`DirectiveHandler`protocol:

python
PYTHON

```
from typing import ClassVar

from patitas.nodes import Directive

class AlertDirective:
    names: ClassVar[tuple[str, ...]] = ("alert",)
    token_type: ClassVar[str] = "alert"

    def parse(self, name, title, options, content, children, location):
        return Directive(
            location=location,
            name=name,
            title=title or "info",
            options=options,
            children=tuple(children),
        )

    def render(self, node, rendered_children, sb):
        level = node.title or "info"
        sb.append(f'<div class="alert alert-{level}">')
        sb.append(rendered_children)
        sb.append("</div>")
```
## When to Extend

Choose the right extension mechanism for your needs:

- Build hooks: Integrate CSS preprocessors, JavaScript bundlers, or custom scripts

- Theme customization: Modify page layouts, add partials, or change styling

- Collections: Enforce frontmatter requirements and get IDE autocompletion

- Custom directives: Add domain-specific content blocks (alerts, embeds, widgets)

- Content sources: Pull content from GitHub, Notion, REST APIs, or databases

## Related Resources

- Architecture Reference (/bengal/docs/reference/architecture/) for understanding Bengal internals

- Protocol Layer (https://github.com/lbliii/bengal/tree/main/docs/architecture/meta/protocols/) for interface contracts

- Build Pipeline (https://github.com/lbliii/bengal/tree/main/docs/architecture/core/pipeline/) for pipeline phase details

- Configuration (/bengal/docs/ship/configuration/) for`bengal.toml`options

## In This Section

Content Sources (/bengal/docs/build-sites/extend/sources/)

Fetch content from external sources

2 pages

Build Hooks (/bengal/docs/build-sites/extend/build-hooks/)

Run external tools before and after Bengal builds

Content Collections (/bengal/docs/build-sites/extend/collections/)

Define typed schemas for frontmatter validation and IDE support

Create Custom Skeletons (/bengal/docs/build-sites/extend/custom-skeletons/)

Build reusable site structure templates with skeleton YAML

Custom Content Sources (/bengal/docs/build-sites/extend/custom-sources/)

Fetch content from APIs, databases, or remote services

Custom Directives (/bengal/docs/build-sites/extend/custom-directives/)

Create custom MyST directive blocks for specialized content

Template Shortcodes (/bengal/docs/build-sites/extend/shortcodes/)

Create template-only embeds without writing Python

Theme Customization (/bengal/docs/build-sites/extend/theme-customization/)

Override templates and customize CSS styling

Writing Plugins (/bengal/docs/build-sites/extend/plugins/)

Create plugins that add directives, template functions, content sources, and build hooks

Related Pages

Build Sites (/bengal/docs/build-sites/)

Write, structure, customize, and extend your Bengal site

Related

persona-extender (/bengal/tags/persona-extender/)