Extension Points

from bengal.content_types.base import ContentTypeStrategy
from bengal.content_types.registry import register_strategy

class NewsStrategy(ContentTypeStrategy):
    """Custom strategy for news articles."""

    default_template = "news/list.html"
    allows_pagination = True

    def sort_pages(self, pages):
        """Sort by date, newest first."""
        from datetime import datetime
        return sorted(
            pages,
            key=lambda p: p.date or datetime.min,
            reverse=True
        )

    def get_template(self, page=None, template_engine=None):
        """Custom template selection."""
        if page and page.source_path.stem == "_index":
            return "news/list.html"
        return "news/single.html"

    def detect_from_section(self, section):
        """Auto-detect news sections."""
        return section.name.lower() in ("news", "announcements")

# Register your strategy (call early in build process)
register_strategy("news", NewsStrategy())

---
title: News
content_type: news
---

from typing import Any
from bengal.parsing.base import BaseMarkdownParser

class CustomMarkdownParser(BaseMarkdownParser):
    def parse(self, content: str, metadata: dict[str, Any]) -> str:
        """Parse markdown to HTML."""
        # Your parsing logic here
        html = self._convert_to_html(content)
        return html

    def parse_with_toc(self, content: str, metadata: dict[str, Any]) -> tuple[str, str]:
        """Parse markdown and extract table of contents."""
        html = self.parse(content, metadata)
        toc_html = self._extract_toc(content)
        return html, toc_html

# Register in parser factory
# (requires modification of bengal/parsing/__init__.py)

from bengal.parsing.backends.patitas import (
    ParseConfig, RenderConfig,
    parse_config_context, render_config_context,
)
from bengal.parsing.backends.patitas.renderers.html import HtmlRenderer
from patitas.parser import Parser

# Configure and parse
with parse_config_context(ParseConfig(tables_enabled=True, math_enabled=True)):
    parser = Parser(source)
    ast = parser.parse()

# Configure and render
with render_config_context(RenderConfig(highlight=True)):
    renderer = HtmlRenderer(source)
    html = renderer.render(ast)

from bengal.rendering.engines import register_engine
from bengal.rendering.template_functions import register_all

class MyEngine:
    def __init__(self, site):
        self.site = site
        self.template_dirs = [site.root_path / "templates"]

        # Environment must satisfy TemplateEnvironment protocol
        # (must have globals, filters, tests as dict-like attributes)
        self._env = MyEnvironment()

        # All 80+ template functions registered automatically!
        register_all(self._env, site)

    def render_template(self, name: str, context: dict) -> str:
        ...

register_engine("myengine", MyEngine)

from bengal.plugins.protocol import Plugin
from bengal.plugins.registry import PluginRegistry

class MyFilterPlugin(Plugin):
    name = "my-filters"
    version = "1.0.0"

    def register(self, registry: PluginRegistry) -> None:
        registry.add_template_filter("custom", lambda value: value.upper())

{{ page.title | custom }}

# In bengal/postprocess/ or custom module
class RobotsGenerator:
    def __init__(self, site):
        self.site = site

    def generate(self) -> None:
        """Generate robots.txt"""
        robots_content = self._build_robots_txt()
        output_path = self.site.output_dir / 'robots.txt'
        output_path.write_text(robots_content)

    def _build_robots_txt(self) -> str:
        # Build robots.txt content
        return "User-agent: *\nDisallow: /admin/"

# Register via plugin phase hook
# registry.on_phase("post_render", my_generator.generate)

from bengal.health.base import BaseValidator
from bengal.health.report import CheckResult, CheckStatus

class CustomValidator(BaseValidator):
    name = "custom"
    description = "Custom validation checks"

    def validate(self, site, build_context=None) -> list[CheckResult]:
        results = []

        # Your validation logic
        for page in site.pages:
            if not self._check_custom_requirement(page):
                results.append(CheckResult(
                    status=CheckStatus.ERROR,
                    message=f"Page {page.title} fails custom check",
                    recommendation="Fix the issue"
                ))

        return results

# Register with health system
# (requires modification of bengal/health/health_check.py)

[health_check.validators]
custom = true

my-theme/
├── templates/
│   ├── base.html
│   ├── page.html
│   └── blog/
│       ├── post.html
│       └── list.html
├── assets/
│   ├── css/
│   │   └── style.css
│   ├── js/
│   │   └── main.js
│   └── fonts/
└── theme.toml  # Theme metadata

theme = "my-theme"

from bengal.plugins.protocol import Plugin
from bengal.plugins.registry import PluginRegistry

class AlertPlugin(Plugin):
    name = "alert-shortcode"
    version = "1.0.0"

    def register(self, registry: PluginRegistry) -> None:
        registry.add_shortcode(
            "alert",
            '<div class="alert alert-{{ type | default("info") }}">{{ content }}</div>',
        )

{{% alert type="warning" %}}
This is a warning message!
{{% /alert %}}

from bengal.plugins.protocol import Plugin
from bengal.plugins.registry import PluginRegistry


class MyPlugin(Plugin):
    name = "my-plugin"
    version = "1.0.0"

    def register(self, registry: PluginRegistry) -> None:
        # Directives and roles
        registry.add_directive(MyDirectiveHandler)
        registry.add_role(MyRoleHandler)

        # Template extensions
        registry.add_template_function("my_func", my_func, phase=1)
        registry.add_template_filter("my_filter", my_filter)
        registry.add_template_test("my_test", my_test)

        # Content and validation
        registry.add_content_source("my-source", MySourceClass)
        registry.add_health_validator(MyValidator())
        registry.add_shortcode("alert", '<div class="alert">{{ content }}</div>')

        # Build lifecycle
        registry.on_phase("pre_render", self.before_render)
        registry.on_phase("post_render", self.after_render)

[project.entry-points."bengal.plugins"]
my-plugin = "my_package:MyPlugin"

import click
from bengal.cli import cli

@cli.command()
@click.option('--verbose', is_flag=True)
def custom(verbose):
    """My custom command."""
    print("Executing custom command")

# Commands automatically discovered and registered

from typing import Any
from pathlib import Path
from bengal.autodoc.base import Extractor, DocElement

class OpenAPIExtractor(Extractor):
    """Extract docs from OpenAPI specs."""

    def extract(self, source: Any) -> list[DocElement]:
        spec = self._load_openapi_spec(source)

        elements = []
        for path, methods in spec['paths'].items():
            for method, details in methods.items():
                element = DocElement(
                    name=f"{method.upper()} {path}",
                    qualified_name=f"api.{method}.{path}",
                    element_type='endpoint',
                    description=details.get('summary', ''),
                    metadata=details
                )
                elements.append(element)

        return elements

    def get_output_path(self, element: DocElement) -> Path | None:
        """Determine output path for the endpoint."""
        return Path(f"api/{element.name.replace(' ', '-').lower()}.md")

# Register extractor
# (planned: autodoc registry system)