DOCX Export Integration

Relevant source files

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

• packages/renderer-docx/src/index.ts
• packages/compiler/src/node.ts
• apps/web/src/app/api/export/docx/route.ts
• chemd-v0.1-architecture.md
• packages/renderer-docx/tests/renderer-docx.test.ts
• packages/compiler/tests/compiler-node.test.ts

The DOCX Export Integration provides a pipeline for transforming structured chemd documents into Microsoft Word (.docx) files. It leverages a multi-stage approach where semantic AST nodes are first converted into an intermediate, export-oriented Markdown format before being processed by Pandoc. This ensures that chemical data, experimental results, and molecular structures are represented accurately in a widely used document format.

The integration is architected as a "thin" layer that bridges the gap between the normalized semantic AST and external document conversion tools. It supports rendering of frontmatter metadata, structured blocks (molecules, reactions, results), and lightweight references, making the output suitable for lab reports and publications.

Architecture and Pipeline

The DOCX export process is designed as a multi-stage pipeline rather than a direct rendering pass. This separation allows for intermediate validation and flexible formatting.

Conversion Stages

1. Compilation: The compileChemd function parses the source into a ChemdDocument AST.
2. Markdown Handoff: The renderDocxMarkdown function transforms the AST into a specific Markdown dialect optimized for Pandoc consumption.
3. Bridge Payload: Optionally, a DocxBridgePayload JSON structure is created containing metadata, diagnostics, and resolved render options for external tools.
4. Pandoc Execution: In Node.js environments, the Markdown is written to a temporary file and passed to a Pandoc process with specific arguments (e.g., --from gfm --to docx).

Sources: packages/renderer-docx/src/index.ts:161-177, packages/compiler/src/node.ts:169-172, packages/renderer-docx/tests/renderer-docx.test.ts:12-25

Key Components

DOCX Renderer (@chemd/renderer-docx)

This package is responsible for the text-based transformation of the AST. It handles the serialization of chemical entities into Markdown equivalents.

Function	Description
renderDocxMarkdown	Converts a ChemdDocument into a Markdown string including frontmatter and structured headings.
createDocxBridgePayload	Generates a structured JSON object containing the document AST and render metadata.
renderStructuredNode	Recursively processes AST nodes (reactions, molecules, etc.) into Markdown list items and headings.

Sources: packages/renderer-docx/src/index.ts:114-160, packages/renderer-docx/src/index.ts:180-192

Node Compiler (@chemd/compiler/node)

Provides the glue logic for executing the conversion on the server side using the system's Pandoc binary.

API and Configuration

Web Export Endpoint

The project provides a Next.js API route for triggering exports.

Endpoint: POST /api/export/docx

Parameter	Type	Required	Description
source	string	Yes	The raw chemd/markdown source text.
profileId	string	No	Specific render profile to apply.
fileName	string	No	Requested name for the resulting file.

Sources: apps/web/src/app/api/export/docx/route.ts:19-23, apps/web/src/app/api/export/docx/route.ts:107-124

Pandoc Arguments

The integration uses specific arguments to ensure compatibility with GitHub Flavored Markdown (GFM) and custom templates.

// Example argument construction
const args = [
  markdownInputPath,
  "--from", "gfm",
  "--to", "docx",
  "--output", outputPath,
  ...(options.referenceDocPath ? ["--reference-doc", options.referenceDocPath] : []),
  ...(options.extraArgs ?? [])
];

Sources: packages/compiler/src/node.ts:46-59

Safety and Limits

To prevent server exhaustion, the export route implements several constraints:

• Concurrency: Managed via MAX_CONCURRENT_DOCX_EXPORTS and a slot acquisition mechanism.
• Request Size: Bodies are limited to MAX_DOCX_EXPORT_REQUEST_BYTES.
• Timeouts: Pandoc execution is wrapped in a timeout (defaulting to DOCX_EXPORT_TIMEOUT_MS).
• Sanitization: Filenames are sanitized to remove unsafe characters.

Sources: apps/web/src/app/api/export/docx/route.ts:32-41, apps/web/src/app/api/export/docx/route.ts:88-101, packages/compiler/src/node.ts:114-125

Data Structures

DocxBridgePayload

The bridge payload is a v0.1 specific structure designed for external consumers.

export interface DocxBridgePayload {
  version: "v0.1";
  document: {
    meta: ChemdDocument["meta"];
    children: ChemdDocument["children"];
  };
  diagnostics: ChemdDocument["diagnostics"];
  render: {
    profileId: string;
    resolvedOptions: RenderOptions;
    adapter?: RenderAdapterPayload;
  };
  exportHints: {
    format: "docx-bridge";
    pipeline: "html-or-markdown-to-docx";
    recommendedTool: "pandoc";
  };
}

Sources: packages/renderer-docx/src/index.ts:4-21

Conclusion

The DOCX Export Integration serves as a robust bridge between the structured chemistry data of chemd and standard document formats. By utilizing a Markdown-centric handoff to Pandoc, the system ensures that complex experimental data is rendered in a readable, professional format while maintaining strict separation between semantic content and visual style.