Documentation Team Lead

bengal collections init

from bengal.collections import define_collection, BlogPost, DocPage

collections = {
    "blog": define_collection(schema=BlogPost, directory="blog"),
    "docs": define_collection(schema=DocPage, directory="docs"),
}

from bengal.collections import BlogPost, DocPage, APIReference, Tutorial, Changelog
# Or use short aliases:
from bengal.collections import Post, Doc, API

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class ProjectPage:
    title: str
    status: str  # "active", "completed", "archived"
    started: datetime
    tech_stack: list[str] = field(default_factory=list)
    github_url: str | None = None

collections = {
    "projects": define_collection(
        schema=ProjectPage,
        directory="projects",
    ),
}

⚠ content/blog/my-post.md
  └─ date: Required field 'date' is missing

[build]
strict_collections = true

define_collection(
    schema=BlogPost,
    directory="blog",
    strict=False,       # Don't reject unknown fields
    allow_extra=True,   # Store extra fields in _extra dict
)

# List defined collections and their schemas
bengal collections list

# Validate content without building
bengal collections validate

# Validate specific collection
bengal collections validate --collection blog

define_collection(
    schema=BlogPost,
    directory="blog",
    glob="*.md",  # Only top-level, not subdirectories
)

def migrate_legacy(data: dict) -> dict:
    if "post_title" in data:
        data["title"] = data.pop("post_title")
    return data

collections = {
    "blog": define_collection(
        schema=BlogPost,
        directory="blog",
        transform=migrate_legacy,
    ),
}

from bengal.collections import define_collection, DocPage
from bengal.content.sources import github_loader

collections = {
    "api-docs": define_collection(
        schema=DocPage,
        loader=github_loader(repo="myorg/api-docs", path="docs/"),
    ),
}

pip install bengal[github]   # GitHub repositories
pip install bengal[notion]   # Notion databases
pip install bengal[rest]     # REST APIs
pip install bengal[all-sources]  # Everything

from bengal.collections import define_collection, DocPage
from bengal.content.sources import github_loader

collections = {
    # Local content (default)
    "docs": define_collection(
        schema=DocPage,
        directory="content/docs",
    ),

    # Remote content from GitHub
    "api-docs": define_collection(
        schema=DocPage,
        loader=github_loader(
            repo="myorg/api-docs",
            path="docs/",
        ),
    ),
}

from bengal.content.sources import github_loader

loader = github_loader(
    repo="owner/repo",       # Required: "owner/repo" format
    branch="main",           # Default: "main"
    path="docs/",            # Default: "" (root)
    token=None,              # Default: uses GITHUB_TOKEN env var
    glob="*.md",             # Default: "*.md" (file pattern to match)
)

from bengal.content.sources import notion_loader

loader = notion_loader(
    database_id="abc123...",  # Required: database ID from URL
    token=None,               # Default: uses NOTION_TOKEN env var
    property_mapping={        # Map Notion properties to frontmatter
        "title": "Name",
        "date": "Published",
        "tags": "Tags",
    },
)

from bengal.content.sources import rest_loader

loader = rest_loader(
    url="https://api.example.com/posts",
    headers={"Authorization": "Bearer ${API_TOKEN}"},  # Env vars expanded
    content_field="body",           # JSON path to content
    id_field="id",                  # JSON path to ID
    frontmatter_fields={            # Map API fields to frontmatter
        "title": "title",
        "date": "published_at",
        "tags": "categories",
    },
)

from bengal.content.sources import local_loader

loader = local_loader(
    directory="content/docs",
    glob="**/*.md",
    exclude=["_drafts/*"],
)

# Check cache status
bengal sources status

# Force refresh from remote
bengal sources fetch --force

# Clear all cached content
bengal sources clear

# List configured content sources
bengal sources list

# Show cache status (age, size, validity)
bengal sources status

# Fetch/refresh from remote sources
bengal sources fetch
bengal sources fetch --source api-docs  # Specific source
bengal sources fetch --force            # Ignore cache

# Clear cached content
bengal sources clear
bengal sources clear --source api-docs

from bengal.collections import define_collection, DocPage
from bengal.content.sources import github_loader, local_loader

collections = {
    # Main docs (local)
    "docs": define_collection(
        schema=DocPage,
        directory="content/docs",
    ),

    # API reference (from API team's repo)
    "api": define_collection(
        schema=DocPage,
        loader=github_loader(repo="myorg/api-service", path="docs/"),
    ),

    # SDK docs (from SDK repo)
    "sdk": define_collection(
        schema=DocPage,
        loader=github_loader(repo="myorg/sdk", path="docs/"),
    ),
}

from collections.abc import AsyncIterator
from bengal.content.sources import ContentSource, ContentEntry

class MyCustomSource(ContentSource):
    source_type = "my-api"

    async def fetch_all(self) -> AsyncIterator[ContentEntry]:
        items = await self._get_items()
        for item in items:
            yield ContentEntry(
                id=item["id"],
                slug=item["slug"],
                content=item["body"],
                frontmatter={"title": item["title"]},
                source_type=self.source_type,
                source_name=self.name,
            )

    async def fetch_one(self, id: str) -> ContentEntry | None:
        item = await self._get_item(id)
        if not item:
            return None
        return ContentEntry(
            id=item["id"],
            slug=item["slug"],
            content=item["body"],
            frontmatter={"title": item["title"]},
            source_type=self.source_type,
            source_name=self.name,
        )

# validators/custom.py
from bengal.health.base import BaseValidator
from bengal.health.report import CheckResult

class RequireAuthorValidator(BaseValidator):
    """Validator that checks for author field in frontmatter."""

    name = "Author Required"
    description = "Ensures all pages have an author field"

    def validate(self, site, build_context=None):
        results = []
        for page in site.pages:
            if not page.metadata.get("author"):
                results.append(CheckResult.error(
                    f"Missing author in {page.source_path}",
                    recommendation="Add 'author: Your Name' to frontmatter",
                    details=[str(page.source_path)],
                ))
        return results

# Run all validators
bengal validate

# Preview auto-fixes
bengal fix --dry-run

# Apply safe fixes
bengal fix

# Validate entire site
bengal validate

# Validate specific file
bengal validate --file content/docs/getting-started.md

# Validate changed files only (git-aware)
bengal validate --changed

# Verbose output - show all checks, not just errors
bengal validate --verbose

# Fail build on validation errors (recommended for CI)
bengal build --strict

# Validate templates before building
bengal build --validate

# Link checking (internal + external)
bengal health linkcheck

# Internal links only (fast)
bengal health linkcheck --internal-only

# External links only
bengal health linkcheck --external-only

# Exclude specific URL patterns
bengal health linkcheck --exclude "^/api/preview/"

$ bengal validate

🔍 Running health checks...

✅ Config: 3 checks passed
✅ Navigation: 5 checks passed
⚠️ Links: 2 warnings
  → content/docs/old-page.md references moved page
  → content/api/client.md has broken anchor #deprecated

❌ Directives: 1 error
  → content/tutorials/setup.md:45 - Unclosed code fence

Summary: 1 error, 2 warnings, 8 passed

bengal fix --dry-run

# Apply safe fixes only (default)
bengal fix

# Apply all fixes including those needing confirmation
bengal fix --all

# Ask before each fix
bengal fix --confirm

# Fix specific validator only
bengal fix --validator Directives

name: Validate Docs

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'

      - name: Install Bengal
        run: pip install bengal

      - name: Validate Content
        run: bengal validate --verbose

      - name: Check Links
        run: bengal health linkcheck --internal-only

      - name: Build (strict mode)
        run: bengal build --strict

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: bengal-validate
        name: Validate Bengal content
        entry: bengal validate --changed
        language: system
        pass_filenames: false

# Strict mode - treats warnings as errors
bengal build --strict

# Validate and exit with error code
bengal validate && echo "Validation passed" || echo "Validation failed"

# validators/require_author.py
from bengal.health.base import BaseValidator
from bengal.health.report import CheckResult, Severity

class RequireAuthorValidator(BaseValidator):
    """Ensure all blog posts have an author."""

    name = "Author Required"
    description = "Validates that blog posts have author metadata"

    def validate(self, site, build_context=None):
        results = []

        for page in site.pages:
            # Only check blog posts
            if not page.section or page.section.name != "blog":
                continue

            if not page.metadata.get("author"):
                results.append(CheckResult(
                    severity=Severity.ERROR,
                    message=f"Missing author in {page.source_path}",
                    recommendation="Add 'author: Your Name' to frontmatter",
                    file_path=page.source_path,
                    line_number=1,
                ))

        return results

# bengal.py (site configuration)
from validators.require_author import RequireAuthorValidator

validators = [
    RequireAuthorValidator(),
]

# config/_default/health.yaml
health:
  validators:
    links:
      enabled: true
      external: false    # Skip external link checks
    performance:
      enabled: false     # Disable performance checks

health:
  linkcheck:
    external: true
    max_concurrency: 10
    timeout: 30
    retries: 2
    exclude:
      - "https://example.com/private/*"
    exclude_domains:
      - "localhost"
      - "*.internal.company.com"

# Full validation (CI)
bengal validate --verbose

# Quick validation (local dev)
bengal validate --changed

# Pre-deploy validation
bengal health linkcheck && bengal build --strict

# Writer profile (fast, less strict) - default
bengal validate --profile writer

# Theme developer profile
bengal validate --profile theme-dev

# Developer profile (strict, all checks)
bengal validate --profile developer

# Ignore specific check codes
bengal validate --ignore H101 --ignore H202

---
validate:
  skip:
    - links        # Skip link validation for this page
    - anchors      # Skip anchor validation
---

# config/_default/health.yaml
health:
  ignore_patterns:
    - "content/drafts/**"
    - "content/archived/**"

# Check internal links only (fast)
bengal health linkcheck --internal-only

# Exclude specific URL patterns
bengal health linkcheck --exclude "^/api/preview/"

# Clear build cache (includes validation state)
bengal clean --cache

# Force full re-validation by clearing cache first
bengal clean --cache && bengal validate

# Use incremental validation (only changed files)
bengal validate --incremental

# Validate
bengal validate                    # Run all validators
bengal validate --changed          # Only changed files
bengal validate --incremental      # Use cached validation state
bengal validate --verbose          # Show all checks
bengal validate --suggestions      # Show quality suggestions
bengal validate --file path.md     # Validate specific file
bengal validate --profile writer   # Use writer profile (fast)
bengal validate --ignore H101      # Ignore specific check codes
bengal validate --watch            # Watch mode (experimental)
bengal validate --templates        # Validate template syntax

# Auto-fix
bengal fix --dry-run               # Preview fixes
bengal fix                         # Apply safe fixes
bengal fix --all                   # Apply all fixes
bengal fix --confirm               # Ask before each fix
bengal fix --validator Directives  # Fix specific validator

# Link checking
bengal health linkcheck                   # Check all links
bengal health linkcheck --internal-only   # Internal only (fast)
bengal health linkcheck --external-only   # External only
bengal health linkcheck --format json     # JSON output for CI

# Build
bengal build --strict              # Fail on warnings
bengal build --validate            # Validate before building

# Clean
bengal clean --cache               # Clear build cache

# bengal.toml
[site]
title = "My Site"
baseurl = "https://example.com"
language = "en"

[build]
output_dir = "public"

[theme]
name = "default"

bengal build --environment production

# config/environments/production.yaml
site:
  baseurl: "https://example.com"

build:
  minify_html: true
  strict_mode: true

assets:
  fingerprint: true

[assets]
minify = true
optimize = true
fingerprint = true

[build]
validate_templates = true

bengal build --environment production

bengal build --environment production --strict --clean-output

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'

      - name: Install Bengal
        run: pip install bengal

      - name: Build Site
        run: bengal build --environment production --strict --clean-output

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './public'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

[build]
  publish = "public"
  command = "bengal build --environment production"

[build.environment]
  PYTHON_VERSION = "3.14"

BENGAL_BASEURL="https://custom-domain.com" bengal build --environment production

# config/environments/production.yaml
site:
  baseurl: "https://example.com"