Module

cli.templates.base

Template system primitives used by all built‑in site templates.

This module defines two dataclasses that describe what a site template is and the files it contributes when instantiated via CLI commands (e.g. bengal new site --template blog). These classes are intentionally small and framework‑agnostic so they can be reused by both built‑in and custom templates.

Key concepts:

  • TemplateFile: a single file that will be written to a target area of the project (content/,data/,templates/, etc.).
  • SiteTemplate: a collection ofTemplateFileitems plus optional directory scaffolding and menu hints that describe a complete starter layout.
View source
3 Classes

Classes

TemplateFile dataclass
Represents a file to be created from a site template. A ``TemplateFile`` encapsulates the rendered…
0

Represents a file to be created from a site template.

ATemplateFileencapsulates the rendered content and the relative path where the file should be placed inside a specific target area of the project tree. The CLI will iterate these instances and write them to disk.

Attributes

Name Type Description
relative_path str

Project‑relative path undertarget_dir(e.g."posts/first-post.md"or"_index.md").
content str

The fully rendered file contents to be written.
target_dir str

Top‑level destination directory. Common values are"content","data", and"templates".
SiteTemplate dataclass
A concrete site template definition. A ``SiteTemplate`` declares all files and optional directorie…
3

A concrete site template definition.

ASiteTemplatedeclares all files and optional directories that should be created when the template is applied. Template providers typically construct one instance per template (e.g.blog,docs) and expose it via a module‑levelTEMPLATEvariable for discovery.

Attributes

Name Type Description
id str

Stable identifier used from the CLI (e.g."blog").
name str

Human‑friendly display name.
description str

One‑line summary shown in listings.
files list[TemplateFile]

Files to materialize when the template is applied.
additional_dirs list[str]

Extra directories to ensure exist before writing files (useful for empty folders that should be tracked).
menu_sections list[str]

Section slugs that can be used by generators to seed a default navigation menu for the site.

Methods 3

get_files
Return all files that should be written for this template.
0 list[TemplateFile] 
def get_files(self) -> list[TemplateFile]

Return all files that should be written for this template.

Returns

list[TemplateFile] —

A list ofTemplateFileinstances in write order.

get_additional_dirs
Return additional directories that should be created.
0 list[str] 
def get_additional_dirs(self) -> list[str]

Return additional directories that should be created.

Returns

list[str] —

A list of directory paths (relative to project root).

get_menu_sections
Return section slugs that can seed menu auto‑generation.
0 list[str] 
def get_menu_sections(self) -> list[str]

Return section slugs that can seed menu auto‑generation.

Returns

list[str] —

A list of section identifiers (e.g.["posts", "about"]).

TemplateProvider
Protocol for template providers. Custom template packages can implement this protocol and expose a…
1

Protocol for template providers.

Custom template packages can implement this protocol and expose a get_templateclassmethod that returns a fully constructed SiteTemplateinstance. The registry will import such providers during discovery.

Inherits from Protocol

Methods 1

get_template classmethod
Return the concrete ``SiteTemplate`` definition for this provider.
0 SiteTemplate 
def get_template(cls) -> SiteTemplate

Return the concreteSiteTemplatedefinition for this provider.

Returns

SiteTemplate