Document Frontmatter
Relevant source files
The following files were used as context for generating this wiki page:
Document Frontmatter in chemd refers to the YAML-based metadata block located at the very beginning of a .md or .chemd.md file. It serves as the primary source of truth for administrative data, document identification, and rendering configuration, effectively acting as the first layer of the four-layer file model in the chemd specification.
Sources: chemd-v0.1-spec.md:25-40, chemd-v0.1-architecture.md:214-219
Metadata Structure and Schema
The frontmatter is delimited by triple dashes (---) and contains key-value pairs that define the experiment's context. The parser enforces specific requirements for document identification and validation.
Recommended and Required Keys
| Key | Type | Required | Description |
|---|---|---|---|
entry_type | string | Yes | The type of entry, typically set to experiment. |
id | string | Yes | A unique identifier for the document within the project space. |
title | string | Yes | The descriptive title of the experiment or record. |
date | string | Yes | The record date, which MUST follow the ISO format YYYY-MM-DD. |
project | string | No | The associated project or research topic. |
status | string | No | Current state: planned, running, completed, failed, or abandoned. |
render_profile | string | No | Identifier for the default visual style (e.g., eln-default). |
primary_* | string | No | Reference pointers to specific block IDs (e.g., primary_reaction). |
tags | string[] | No | An array of labels for categorization. |
Sources: chemd-v0.1-spec.md:42-70, packages/parser/src/frontmatter/parse-frontmatter.ts:258-301
Data Flow for Frontmatter Parsing
The following diagram illustrates how the chemd parser processes the raw source text to extract frontmatter metadata before proceeding to the document body.
The parser utilizes a hybrid approach where the frontmatter is stripped first to build the ChemdMeta object, which is then attached to the final ChemdDocument node.
Sources: packages/parser/src/index.ts:5-15, packages/parser/src/frontmatter/parse-frontmatter.ts:405-430
Validation and Error Handling
The frontmatter parser implements strict validation rules to ensure document integrity. If a required key like id or date is missing, the parser defaults to a "draft-document" ID and a "1970-01-01" date while emitting error diagnostics.
Common Diagnostic Codes
- E_MISSING_REQUIRED_FRONTMATTER_KEY: Triggered when
id,title, ordateare absent. - W_NON_ISO_FRONTMATTER_DATE: Warning issued if the date does not match the
YYYY-MM-DDpattern. - W_DUPLICATE_FRONTMATTER_KEY: Occurs when a key is defined multiple times; the last value wins.
- E_INVALID_FRONTMATTER_VALUE: Generic error for incorrect data types (e.g., an object where a string was expected).
Sources: packages/parser/src/frontmatter/parse-frontmatter.ts:11-23, packages/parser/tests/parser.test.ts:410-445
Rendering Configuration
One of the critical roles of the frontmatter is separating semantic data from visual style. This is achieved through render_profile and render_overrides.
Render Profiles
The render_profile key selects a predefined set of visual parameters. If an unknown profile is provided, the system falls back to the implementation default (typically eln-default) and issues a W_UNKNOWN_RENDER_PROFILE warning.
Sources: chemd-v0.1-architecture.md:323-335, packages/compiler/tests/compiler.test.ts:130-145
Render Overrides
The render_overrides key allows for document-level adjustments to specific style properties without altering the semantic AST.
render_overrides:
structure.bondLineWidth: 2.1
reaction.showConditionsBelowArrow: false
export.margin: 16
The parser validates these keys against a known allowlist and ensures the values match required types (e.g., structure.bondLineWidth must be a positive number).
Sources: packages/parser/src/frontmatter/parse-frontmatter.ts:145-195, packages/parser/tests/parser.test.ts:140-160
Integration with Lightweight References
Frontmatter keys can be referenced within the Markdown body or templates using the @meta.key syntax. This allows for dynamic content generation where the metadata serves as a variable source.
Experiment Title: @meta.title
Project ID: @meta.project
The resolver maps these tokens directly to the properties stored in the meta object of the ChemdDocument.
Sources: chemd-v0.1-spec.md:185-195, packages/resolver/tests/resolver.test.ts:25-35
Summary
Document Frontmatter provides the structural backbone for chemd files, ensuring that every experiment is uniquely identified and properly categorized. By separating rendering configuration (render_profile) from experiment data, it maintains a clean boundary between semantic content and visual presentation, while providing the necessary metadata for the lightweight reference and template systems.
Sources: chemd-v0.1-spec.md:75-85, chemd-v0.1-architecture.md:85-95