Introduction to cheMD

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
• AGENTS.md
• chemd-render-profile-v0.1-spec.md
• packages/parser/tests/parser.test.ts
• packages/renderer-html/src/index.ts
• packages/compiler/tests/compiler.test.ts

chemd is a Markdown-based domain language designed for chemistry-focused electronic lab notebooks (ELN). Its primary goal is to represent chemical and experimental data as structured blocks within a standard Markdown environment, ensuring that the .md file remains the source of truth while supporting downstream rendering to formats like HTML, JSON, SVG, and DOCX.

The system is designed to keep daily authoring close to normal Markdown while providing powerful features like lightweight references, reusable templates with parameter injection, and a strict separation between semantic content and rendering style.

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

Language Model and File Structure

A chemd document is structured into four distinct layers: YAML frontmatter for metadata, normal Markdown body for prose, chemd inline/block syntax for structured data, and optional render profile selection.

Document Layers

Layer	Purpose	Requirements
YAML Frontmatter	Stores document metadata like id, title, and date.	MUST start the document; uses YYYY-MM-DD for dates.
Markdown Body	Standard prose for experimental narratives.	UTF-8 encoding required.
cheMD Syntax	Structured blocks (molecule, reaction, etc.) and inline chemistry.	Uses fenced directive-style syntax (:::block_name).
Render Profile	Metadata for selecting visual styles.	Separate from semantic content.

Sources: chemd-v0.1-spec.md:18-30, chemd-v0.1-spec.md:46-64

Core Design Principles

1. Semantic/Style Separation: Chemical data (SMILES, amounts) is kept separate from visual parameters (bond length, font size).
2. Graceful Degradation: Unknown syntax should not break the document rendering.
3. Single Source of Truth: Metadata and experiment logic are declared once and referenced as needed.

Sources: chemd-v0.1-spec.md:33-41, chemd-v0.1-spec.md:73-86

Architecture Overview

The cheMD system follows a multi-stage pipeline architecture that transforms raw text into a variety of outputs through several normalization and resolution phases.

Transformation Pipeline

The diagram below illustrates the flow from a source .md file to final rendered outputs.

This pipeline ensures that syntax parsing remains independent from semantic resolution and visual styling.

Sources: chemd-v0.1-architecture.md:66-90

System Components

The project is organized as a monorepo with specialized packages:

• packages/core: Shared AST types and standard block definitions.
• packages/parser: Responsible for detecting chemd syntax and building the initial AST.
• packages/resolver: Handles object indexing, @id reference lookups, and template expansion.
• packages/render-profile: Merges default styles with document-level overrides.
• packages/renderer-html: Transforms the resolved AST into an HTML preview.

Sources: chemd-v0.1-architecture.md:95-135, AGENTS.md:10-18

Standard Block Types

chemd provides several built-in block types to capture structured experimental data. All blocks use the :::block_name #id header format.

Molecule Block

Used to represent single molecular objects with structural data.

• Required Fields: smiles
• Optional Fields: name, formula, amount, role, caption

Sources: chemd-v0.1-spec.md:168-202

Reaction Block

Captures chemical transformations.

• Required Fields: reactants, products (separated by |)
• Optional Fields: catalyst, solvent, temperature, time, yield, conditions

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

Analytical and Results Blocks

Block Type	Primary Fields	Purpose
result	yield, conversion, isolated_mass	Standardized experiment outcomes.
analysis	type, data, instrument, solvent	Analytical characterization (e.g., NMR).
sample	name, sample_id, batch, supplier	Tracking source materials.

Sources: chemd-v0.1-spec.md:247-285

Reference and Template System

chemd supports a lightweight syntax for linking data across the document, reducing redundancy.

Reference Syntax

• Object Reference: @id (e.g., See @rxn-main)
• Field Reference: @id.field (e.g., @res-main.yield)
• Meta Reference: @meta.key (reads from frontmatter)

Sources: chemd-v0.1-spec.md:287-310

Templating

Templates allow for reusable Markdown structures. A template block defines the structure, and a use block injects data or overrides.

:::template quick-summary
bind: reaction=primary_reaction | result=primary_result
## Summary
Temp: @reaction.temperature
Yield: @result.yield
:::

:::use quick-summary
:::

The resolver expands these blocks into standard Markdown nodes during processing.

Sources: chemd-v0.1-spec.md:316-370, packages/resolver/tests/resolver.test.ts:68-100

Rendering and Styles

The Render Profile system controls visual output without modifying the semantic data. This allows the same experiment to be rendered for an ELN preview, a publication (ACS style), or a presentation.

Profile Resolution

The final style is calculated by merging four levels of configuration:

1. Built-in base defaults.
2. Parent profile (via extends).
3. Selected profile (e.g., publication-acs).
4. Document-level render_overrides in frontmatter.

Structure Styling Options

Option	Type	Description
bondLength	number	Target length of chemical bonds.
bondLineWidth	number	Width of bond lines.
monochrome	boolean	Toggles between color and black-and-white mode.
fontSize	number	Base font size for atom labels.

Sources: chemd-render-profile-v0.1-spec.md:65-80

Diagnostics and Validation

To ensure document integrity, chemd provides a diagnostic system that surfaces errors and warnings during parsing and resolution.

• Errors (E): Critical issues like E_DUPLICATE_ID, E_MISSING_REQUIRED_FIELD, or E_TEMPLATE_CYCLE.
• Warnings (W): Non-breaking issues like W_UNKNOWN_FIELD, W_UNRESOLVED_REFERENCE, or W_NON_ISO_FRONTMATTER_DATE.

Sources: chemd-v0.1-architecture.md:341-365, packages/parser/tests/parser.test.ts:460-475

Conclusion

chemd provides a robust, developer-friendly architecture for handling chemical experimental data within Markdown. By separating semantic meaning from visual representation and utilizing a powerful reference/template system, it enables researchers to maintain high-quality, machine-readable records that remain easy for humans to read and edit.