Fundamental concepts for understanding and using Chalk.

Content Policies

Content policies define what types of content can appear within different sections of elements and documents. Each section (body, detail) can have its own content policy:

• Array of strings: ['paragraph', 'image', 'code-block'] - specifies allowed element identifiers
• ContentPolicy enum: 'literal' - allows raw text content without parsing elements
• null: No content allowed (empty element)

Where ContentPolicy is used:

• bodyPolicy: Controls content in the main area of elements and documents
• detailPolicy: Controls content in the detail/sidebar area of elements

Document Classes

A document class is simply the name/identifier you assign to a document type (e.g., ‘blog-post’, ‘article’, ‘book’). It defines the structure and allowed content for documents of that type. Every library starts with a document definition that specifies:

• Class name: The identifier/name for your document type
• Body policy: What elements can appear in the document body
• Header attributes: Required metadata for documents of this type

Elements vs. Primitives

• Elements: User-defined components with custom behavior, validation, and content rules
• Primitives: Built-in elements that handle common patterns (headings, paragraphs, etc.)

Libraries

Libraries are collections of definitions that tell Chalk how to parse and validate documents:

• Document Definition: Defines the overall document structure
• Element Definitions: Define custom elements and their behavior
• Attribute Types: Define custom validation for attribute values
• Enums: Define fixed sets of allowed values

Result Pattern

Chalk uses a Result pattern for error handling:

interface Result<T, E> {
  ok: boolean;
  data?: T;    // Present when ok: true
  error?: E;   // Present when ok: false
}

This pattern provides explicit error handling without exceptions.

Next Steps

• API Documentation - Back to API documentation index
• API Methods - Complete API reference
• Defining Libraries - How to create custom libraries
• Primitive Reference - Built-in elements and types
• Language Guide - Learn the Chalk language
• Home - Back to documentation home