Module

`collections.schemas`

Standard collection schemas for common content types.

Provides ready-to-use dataclass schemas for blog posts, documentation pages, API references, tutorials, and changelogs. Use these directly or extend them for custom content types.

Available Schemas:

BlogPost (alias: Post): Blog posts with date, author, tags
DocPage (alias: Doc): Documentation with weight, category, toc
APIReference (alias: API): API endpoint documentation
Tutorial: Guides with difficulty, duration, prerequisites
Changelog: Release notes with version, breaking changes

Quick Start:

Use schemas directly in your collections:

>>> from bengal.collections import define_collection
>>> from bengal.collections.schemas import BlogPost, DocPage
>>>
>>> collections = {
...     "blog": define_collection(schema=BlogPost, directory="content/blog"),
...     "docs": define_collection(schema=DocPage, directory="content/docs"),
... }

Extending Schemas:

Create custom schemas by subclassing:

>>> from dataclasses import dataclass
>>> from bengal.collections.schemas import BlogPost
>>>
>>> @dataclass
... class MyBlogPost(BlogPost):
...     '''Extended blog post with custom fields.'''
...     series: str | None = None
...     reading_time: int | None = None

Custom Schemas:

For complete control, define your own dataclass:

>>> from dataclasses import dataclass, field
>>> from datetime import datetime
>>>
>>> @dataclass
... class Product:
...     name: str
...     price: float
...     sku: str
...     in_stock: bool = True
...     categories: list[str] = field(default_factory=list)

Classes

BlogPost 8 ▼

Standard schema for blog posts. Provides common fields for blog content including publication meta…

Standard schema for blog posts.

Provides common fields for blog content including publication metadata, authorship, and categorization.

Attributes

Name	Type	Description
`title`	`str`	Post title displayed in listings and page header. Required.
`date`	`datetime`	Publication date used for sorting and display. Required. Accepts ISO 8601 strings (e.g.,`"2025-01-15"`) or datetime objects.
`author`	`str`	Post author name. Defaults to`"Anonymous"`.
`tags`	`list[str]`	List of tags for categorization and filtering.
`draft`	`bool`	If`True`, page is excluded from production builds.
`description`	`str \| None`	Short description for meta tags, social sharing, and listings.
`image`	`str \| None`	Featured image path (relative to assets) or absolute URL.
`excerpt`	`str \| None`	Manual excerpt. If not set, Bengal auto-generates from content.

DocPage 8 ▼

Standard schema for documentation pages. Optimized for technical documentation with navigation ord…

Standard schema for documentation pages.

Optimized for technical documentation with navigation ordering, categorization, and version tracking.

Attributes

Name	Type	Description
`title`	`str`	Page title. Required.
`weight`	`int`	Sort order within section. Lower values appear first. Defaults to`0`.
`category`	`str \| None`	Category for grouping in navigation (e.g.,`"Reference"`).
`tags`	`list[str]`	List of tags for cross-referencing and filtering.
`toc`	`bool`	Whether to show the table of contents. Defaults to`True`.
`description`	`str \| None`	Page description for meta tags and search results.
`deprecated`	`bool`	If`True`, displays a deprecation warning banner.
`since`	`str \| None`	Version when the documented feature was introduced (e.g.,`"1.2.0"`).

APIReference 8 ▼

Standard schema for API reference documentation. Designed for REST API endpoint documentation with…

Standard schema for API reference documentation.

Designed for REST API endpoint documentation with HTTP method, authentication, and rate limiting metadata.

Attributes

Name	Type	Description
`title`	`str`	Human-readable name for the endpoint. Required.
`endpoint`	`str`	API endpoint path (e.g.,`"/api/v1/users"`). Required.
`method`	`str`	HTTP method. Defaults to`"GET"`. Common values: `"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`.
`version`	`str`	API version string. Defaults to`"v1"`.
`deprecated`	`bool`	If`True`, marks the endpoint as deprecated.
`auth_required`	`bool`	Whether authentication is required. Defaults to`True`.
`rate_limit`	`str \| None`	Rate limit description (e.g.,`"100 req/min"`).
`description`	`str \| None`	Endpoint description for listings and meta tags.

Changelog 6 ▼

Standard schema for changelog entries. Designed for release notes and version history, with suppor…

Standard schema for changelog entries.

Designed for release notes and version history, with support for semantic versioning and breaking change indicators.

Attributes

Name	Type	Description
`title`	`str`	Release title (e.g.,`"v1.2.0"` or `"Version 1.2.0"`). Required.
`date`	`datetime`	Release date. Required. Accepts ISO 8601 strings or datetime.
`version`	`str \| None`	Semantic version string (e.g.,`"1.2.0"`). Optional but recommended for automated version tracking.
`breaking`	`bool`	If`True`, indicates the release contains breaking changes.
`draft`	`bool`	If`True`, the release is not yet published.
`summary`	`str \| None`	Short release summary for listings and feeds.

Tutorial 7 ▼

Standard schema for tutorial and guide pages. Designed for step-by-step learning content with diff…

Standard schema for tutorial and guide pages.

Designed for step-by-step learning content with difficulty levels, time estimates, and series organization.

Attributes

Name	Type	Description
`title`	`str`	Tutorial title. Required.
`difficulty`	`str \| None`	Skill level. Recommended values:`"beginner"`, `"intermediate"`, `"advanced"`.
`duration`	`str \| None`	Estimated completion time (e.g.,`"30 minutes"`).
`prerequisites`	`list[str]`	List of prerequisite knowledge or tutorials.
`tags`	`list[str]`	List of tags for categorization and filtering.
`series`	`str \| None`	Name of the tutorial series this belongs to.
`order`	`int \| None`	Position within the series (1, 2, 3, ...). Used for navigation ordering.