Inline Chemistry Syntax
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Inline Chemistry Syntax in chemd v0.1 provides a dedicated notation for embedding chemical formulas, ionic expressions, and simple reaction equations directly within the Markdown body of a document. It is designed to be display-oriented, keeping daily authoring close to standard Markdown while allowing the system to recognize and render chemical entities with specialized tools like KaTeX and the mhchem extension.
The syntax is primarily used for molecular formulas (e.g., $H_2O$), ionic formulas (e.g., $SO_4^{2-}$), and short in-text chemistry expressions. Unlike structured blocks, inline chemistry is restricted to display purposes and cannot carry complex metadata or be nested.
Sources: chemd-v0.1-spec.md:6-14, chemd-v0.1-spec.md:126-144, chemd-v0.1-architecture.md:52-53
Syntax Definition
The inline syntax follows the pattern :chem[...]. The content inside the brackets is treated as a chemical expression.
Usage Examples
| Syntax | Intended Output |
|---|---|
:chem[H2O] | Molecular formula for Water |
:chem[SO4^2-] | Ionic formula for Sulfate |
:chem[2H2 + O2 -> 2H2O] | Simple reaction equation |
Sources: chemd-v0.1-spec.md:131-135
Constraints and Rules
- No Nesting: Nested
:chem[...]structures are considered invalid. - Display Only: The syntax SHOULD NOT carry metadata; it is intended for visual representation.
- Graceful Degradation: Unknown syntax should degrade gracefully where possible to maintain document readability.
Sources: chemd-v0.1-spec.md:141-144, chemd-v0.1-spec.md:65-66
Architecture and Data Flow
The processing of inline chemistry follows a multi-stage pipeline, transitioning from raw text to a structured Abstract Syntax Tree (AST) node, and finally to a rendered HTML component.
Pipeline Overview
The system identifies inline chemistry during the initial Markdown parsing stage. The parser intercepts the :chem directive and converts it into a specialized token within the Markdown node.
Sources: chemd-v0.1-architecture.md:80-92, packages/parser/tests/parser.test.ts:318-325
Token Data Structure
The InlineChemToken captures the raw input and the extracted chemical value, alongside source mapping information for diagnostics and editor synchronization.
{
"type": "inline_chem",
"raw": ":chem[H2O]",
"value": "H2O",
"start": 28,
"end": 38,
"startLine": 1,
"startColumn": 29
}
Sources: packages/core/tests/core.test.ts:37-46, packages/parser/tests/parser.test.ts:333-335
Implementation Details
Parsing Logic
The parser is responsible for identifying the :chem[...] pattern within text segments. During parseChemd, it populates an inlineChem array within a MarkdownNode.
// From parser.test.ts
const markdown = doc.children.find(child => child.type === "markdown");
expect(markdown.inlineChem[0]).toMatchObject({
raw: ":chem[H2O]",
value: "H2O"
});
Sources: packages/parser/tests/parser.test.ts:332-334, packages/renderer-html/src/index.ts:241-248
Rendering Logic
The HTML renderer converts these tokens into specific HTML spans. It uses a data-chem attribute to store the chemical value, which is typically targeted by front-end chemistry rendering libraries like KaTeX + mhchem.
The renderer ensures that chemical formulas are correctly escaped to prevent HTML injection while preserving the formula's semantic content for the data-chem attribute.
Sources: packages/renderer-html/src/index.ts:55-63, chemd-v0.1-architecture.md:52-53
Diagnostics and Validation
The system monitors the syntax for potential issues during the parsing and resolution stages.
| Diagnostic Code | Severity | Description |
|---|---|---|
W_UNTERMINATED_BLOCK | Warning | Triggered if a chem-like directive is started but not closed properly. |
W_UNKNOWN_BLOCK | Warning | Used if the syntax resembles a directive but fails validation. |
Sources: chemd-v0.1-architecture.md:275-285, packages/parser/tests/parser.test.ts:303-311
Conclusion
Inline Chemistry Syntax provides a lightweight, human-readable way to integrate chemistry into laboratory notebooks. By separating the semantic representation (:chem[H2O]) from the rendering engine (KaTeX/mhchem), the project ensures that chemistry data remains structured and portable across different output formats like HTML, SVG, and JSON.
Sources: chemd-v0.1-spec.md:12-14, chemd-v0.1-architecture.md:21-30