Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
The cheMD repository is a monorepo built using a pnpm workspace and Turborepo. It is designed to provide a Markdown-based domain language for chemistry-focused Electronic Lab Notebooks (ELN). The project architecture separates semantic chemical data from visual rendering styles, allowing a single source document to drive multiple outputs including HTML previews, JSON data, and SVG visuals.
Sources: AGENTS.md:10-17, chemd-v0.1-architecture.md:5-15
Repository Structure
The project is organized into apps and packages. Logic is primarily implemented within the packages and then integrated into the web application.
| Directory | Description |
|---|---|
apps/web | Next.js 15 application serving as the UI entry point. |
packages/core | Shared domain types, AST definitions, and utilities. |
packages/parser | Markdown and frontmatter parsing, semantic block detection. |
packages/resolver | Object/template indexing and reference resolution. |
packages/compiler | Orchestration layer connecting parser, resolver, and renderers. |
packages/renderer-* | Target-specific renderers (HTML, SVG, JSON, DOCX). |
docs | Specifications and architecture documentation. |
Sources: AGENTS.md:12-21, chemd-v0.1-architecture.md:88-124
Development Environment Setup
To set up the project locally, ensure you have pnpm installed. The workflow follows standard monorepo patterns managed via Turborepo.
Prerequisites & Installation
Run the following command at the repository root to install all workspace dependencies:
pnpm install
Sources: AGENTS.md:23-26
Local Development Commands
The following commands are used for development, testing, and building the project:
| Command | Action |
|---|---|
pnpm dev | Starts the local web development server (@chemd/web) via Turbo. |
pnpm build | Compiles and type-checks all workspaces. |
pnpm test | Runs all Vitest suites across the monorepo. |
pnpm typecheck | Executes full TypeScript strict-mode checks. |
pnpm --filter <pkg> test | Runs tests for a specific package (e.g., @chemd/parser). |
Sources: AGENTS.md:23-33
Technical Architecture & Data Flow
The cheMD system operates as a multi-stage pipeline. The transition from raw Markdown to a rendered chemical document involves several distinct processing layers.
Processing Pipeline
The diagram below illustrates the flow of data from a .md source file to the final output.
The pipeline ensures that syntax parsing is independent of semantic resolution and that style (Render Profile) remains strictly separated from content (AST).
Sources: chemd-v0.1-architecture.md:52-70, packages/compiler/tests/compiler.test.ts:13-40
Coding Standards & Workflow
The repository enforces strict TypeScript mode and a standardized commit message format.
Naming & Style
- Indentation: 2 spaces, double quotes, semicolons.
- Naming:
camelCasefor variables/functions,PascalCasefor React components, andkebab-casefor packages. - Exports: Public APIs must be exported from
src/index.tswithin each package.
Sources: AGENTS.md:38-44
Commit Guidelines
Commit messages must follow the conventional commits format: <type>[scope]: <description>.
| Type | Meaning |
|---|---|
feat | New feature (Minor version) |
fix | Bug fix (Patch version) |
docs | Documentation changes |
refactor | Code change that neither fixes a bug nor adds a feature |
test | Adding or fixing tests |
Sources: AGENTS.md:46-75
Local Playground Integration
The apps/web project contains a playground that integrates the full compiler stack. It uses a CompileResult object generated by @chemd/compiler to provide real-time feedback.
The playground supports features like OCR imports and Ketcher-based structure editing, which update the source Markdown directly.
Sources: apps/web/src/app/page.tsx:75-120, chemd-v0.1-architecture.md:44-50
Conclusion
Setting up cheMD locally requires a standard pnpm environment. The project's strength lies in its modular package structure, allowing developers to work on parsing, resolution, or rendering in isolation before verifying changes through the integrated web playground and monorepo-wide test suites.