Chemistry Block Syntax

Relevant source files

The following files were used as context for generating this wiki page:

• chemd-v0.1-spec.md
• chemd-v0.1-architecture.md
• packages/parser/tests/parser.test.ts
• packages/renderer-html/src/index.ts
• packages/resolver/tests/resolver.test.ts
• packages/compiler/tests/compiler.test.ts

The Chemistry Block Syntax is the core structural mechanism of the chemd language, designed to represent chemical and experimental data as structured blocks rather than loose prose. It utilizes a fenced directive-style syntax that integrates seamlessly with standard Markdown while providing a rigorous model for domain-specific entities such as molecules, reactions, and analytical results.

These blocks serve as the primary source of truth for the Semantic AST, allowing the system to distinguish between decorative Markdown content and actionable scientific data. The architecture ensures a strict separation between semantic content (data) and rendering style (visuals), which is managed via independent render profiles.

Sources: chemd-v0.1-spec.md:5-15, chemd-v0.1-architecture.md:27-40

Block Structure and Grammar

All chemistry blocks follow a standard general form consisting of a header and a body. The syntax is designed for easy parsing while maintaining readability.

Block Header

The header defines the block type and an optional unique identifier.

• Syntax: :::<block_name> [#<id>]
• ID Rules: Must start with a letter and contain only alphanumeric characters, underscores, or hyphens ([a-zA-Z][a-zA-Z0-9_-]*). IDs are introduced with a # symbol.

Sources: chemd-v0.1-spec.md:129-148

Block Body

The body contains data defined as key-value pairs.

• Format: key: value (one field per line).
• Naming: Field names are case-sensitive and typically use snake_case.
• Lists: Flat lists use | as a separator (e.g., reactants: CCO | O=O).
• Nesting: Standard chemd v0.1 does not support nested YAML inside blocks, though specialized blocks like col-x can contain nested structured blocks using a brace {:::block ... :::} syntax.

Sources: chemd-v0.1-spec.md:150-165, packages/parser/tests/parser.test.ts:225-235

Core Processing Pipeline

The processing of block syntax follows a multi-stage pipeline that transforms raw text into a resolved, renderable document.

The pipeline ensures that syntax parsing remains independent of semantic resolution and final rendering.

Sources: chemd-v0.1-architecture.md:73-88

Standard Block Types

chemd v0.1 defines several standard block types, each with specific required and optional fields.

Molecule Block

Represents a single molecular object, primarily defined by its SMILES string.

Field	Type	Required	Description
smiles	string	Yes	The chemical structure source.
name	string	No	Human-readable name of the molecule.
role	string	No	Experiment role (e.g., reactant, product).
formula	string	No	Molecular formula.

Sources: chemd-v0.1-spec.md:175-200

Reaction Block

Models a chemical reaction involving multiple participants and conditions.

Field	Type	Required	Description
reactants	list	Yes	List of reactant SMILES or IDs.
products	list	Yes	List of product SMILES or IDs.
conditions	list	No	Reaction environment (temp, time, etc.).
yield	string	No	Reported yield percentage.

Sources: chemd-v0.1-spec.md:204-245, packages/parser/tests/parser.test.ts:316-328

Analytical Blocks (result, analysis, sample)

Used for characterizing the outcome of experiments and managing materials.

• result: Captures yields, conversions, and product states.
• analysis: Stores instrumental data (NMR, HPLC) and instrument settings.
• sample: Tracks batch IDs, purity, and suppliers.

Sources: chemd-v0.1-spec.md:248-295

Template and Layout Blocks

Specialized blocks exist for content reuse and visual arrangement.

Template and Use Blocks

The template system allows authors to define reusable fragments of Markdown and chemd blocks.

• template: Defines a named fragment. It supports bind for mapping aliases to document metadata or specific object IDs.
• use: Executes a template, optionally providing parameter overrides.

Layout (col) Blocks

The col-x block allows side-by-side layout of content.

• Syntax: :::col-<number>
• Internal structure: Uses col: {:::block ... :::} or col: text to define column contents.

Sources: packages/parser/tests/parser.test.ts:225-240, packages/renderer-html/src/index.ts:580-595

Reference Syntax

Blocks are integrated into the document narrative through a lightweight reference syntax:

• @id: References an entire object.
• @id.field: Retrieves a specific value from a block (e.g., @res-main.yield).
• @meta.key: Retrieves a value from the YAML frontmatter.

Sources: chemd-v0.1-spec.md:298-318

Validation and Diagnostics

The system performs strict validation on block syntax to ensure data integrity.

Code	Severity	Trigger
E_DUPLICATE_ID	Error	Two blocks share the same #id.
E_MISSING_REQUIRED_FIELD	Error	A block (e.g., molecule) lacks a required field (smiles).
W_UNKNOWN_FIELD	Warning	A field is present that is not in the block's specification.
W_UNTERMINATED_BLOCK	Warning	A block starts with ::: but does not close correctly.

Sources: chemd-v0.1-spec.md:435-455, packages/parser/tests/parser.test.ts:258-270, chemd-v0.1-architecture.md:435-455

The Chemistry Block Syntax provides a robust framework for structured data entry in lab notebooks. By enforcing a clear separation between data (blocks) and presentation (profiles), it ensures that experimental records remain machine-readable and durable across different rendering environments.