remark-mdd

remark plugins for MDD (Markdown Document) format - Transform semantic markdown into professional business documents.

What is MDD?

MDD (Markdown Document) is a semantic document layer that bridges AI-generated markdown with professional business document output. It extends standard markdown with minimal semantic directives to preserve document structure and intent across formats (HTML, PDF, DOCX).

This package provides the core remark plugins and validation library. For CLI tools, see @markdownkit/mdd.

Features

• 🔌 Remark plugins for MDD document structure and text formatting
• ✅ Validation library with JSON Schema and TypeScript types
• 📐 Semantic directives - letterheads, signatures, headers, footers
• 🎯 Type-safe - Complete TypeScript definitions
• 📦 Lightweight - Just the plugins, no CLI bloat
• 🔧 Extensible - Build custom MDD tools

Installation

npm install @markdownkit/remark-mdd
# or
pnpm add @markdownkit/remark-mdd
# or
yarn add @markdownkit/remark-mdd

Usage

Basic Usage

import { remark } from "remark";
import remarkMddDocumentStructure from "@markdownkit/remark-mdd/plugins/document-structure";
import remarkMddTextFormatting from "@markdownkit/remark-mdd/plugins/text-formatting";
import remarkHtml from "remark-html";

const processor = remark()
  .use(remarkMddDocumentStructure)
  .use(remarkMddTextFormatting)
  .use(remarkHtml, { sanitize: false });

const result = await processor.process(`
::letterhead
ACME Corporation
123 Business Ave
::

# Invoice

Total: $1,234^00^
`);

console.log(String(result));

Using Named Exports

import {
  remarkMddDocumentStructure,
  remarkMddTextFormatting,
  remarkMdxConditional,
} from "@markdownkit/remark-mdd";

With Validation

import { validateDocument } from "@markdownkit/remark-mdd/validator";

const content = `---
title: My Invoice
document-type: invoice
date: 2024-12-15
---

# Invoice
`;

const validation = validateDocument(content);

if (!validation.valid) {
  console.error("Validation errors:", validation.errors);
}

TypeScript

import type {
  MDDFrontmatter,
  DirectiveType,
  ValidationResult,
} from "@markdownkit/remark-mdd/types";

const frontmatter: MDDFrontmatter = {
  title: "My Document",
  "document-type": "business-letter",
  date: "2024-12-15",
};

Plugins

remark-mdd-document-structure

Transforms MDD semantic directives into LaTeX-style markup that preserves document intent.

Supported directives:

• ::letterhead ... :: - Company/organization header
• ::header ... :: - Page header
• ::footer ... :: - Page footer
• ::contact-info ... :: - Contact details block
• ::signature-block ... :: - Signature lines
• ::page-break :: - Force page break
• ::: section-break ::: - Section divider

Example:

::letterhead
ACME Corporation
123 Business Avenue
San Francisco, CA 94102
::

# Business Proposal

remark-mdd-text-formatting

Handles professional typography and text formatting specific to business documents.

Supported patterns:

• text^super^ → <sup>super</sup> (superscripts)
• text~sub~ → <sub>sub</sub> (subscripts)
• @section-1 → Auto-linked internal references
• Automatic section numbering (1, 1.1, 1.1.1)
• Legal clause detection (WHEREAS, THEREFORE)

Example:

The total is $1,234^56^

See @section-2 for details.

remark-mdx-conditional

Conditional processing for MDX content (experimental).

Exports

The package provides multiple export paths for different use cases:

// Main export (all plugins)
import * from '@markdownkit/remark-mdd';

// Individual plugins
import remarkMddDocumentStructure from '@markdownkit/remark-mdd/plugins/document-structure';
import remarkMddTextFormatting from '@markdownkit/remark-mdd/plugins/text-formatting';
import remarkMdxConditional from '@markdownkit/remark-mdd/plugins/mdx-conditional';

// Validation
import { validateDocument } from '@markdownkit/remark-mdd/validator';
import { validateDirectiveEndMarker } from '@markdownkit/remark-mdd/plugin-validator';

// Schema
import schema from '@markdownkit/remark-mdd/schema';
import requirements from '@markdownkit/remark-mdd/schema/requirements';

// TypeScript types
import type { MDDFrontmatter, ValidationResult } from '@markdownkit/remark-mdd/types';

Validation

The package includes comprehensive document validation:

import { validateDocument } from "@markdownkit/remark-mdd/validator";

const result = validateDocument(content, {
  validateFrontmatterFlag: true,
  validateDirectivesFlag: true,
  validateRequirementsFlag: true,
  validateClassesFlag: true,
  strict: false,
});

console.log(result);
// {
//   valid: false,
//   errors: [...],
//   warnings: [...],
//   frontmatter: {...},
//   directives: [...],
//   directiveCounts: {...}
// }

Validation features:

• ✅ Frontmatter schema validation (required fields, date formats)
• ✅ Directive structure validation (end markers, nesting, duplicates)
• ✅ Document type requirements (per-type required/recommended elements)
• ✅ Semantic class validation (whitelist of valid CSS classes)
• ✅ Detailed error messages with line numbers and suggestions

JSON Schema

JSON Schema definitions are included for IDE integration and validation:

import schema from "@markdownkit/remark-mdd/schema";
import requirements from "@markdownkit/remark-mdd/schema/requirements";

// Use with AJV, JSON Schema validators, etc.

VS Code integration:

{
  "yaml.schemas": {
    "node_modules/@markdownkit/remark-mdd/schema/mdd-document.schema.json#/definitions/frontmatter": "*.mdd"
  }
}

TypeScript Types

Complete TypeScript definitions are provided:

import type {
  // Document structure
  MDDFrontmatter,
  MDDDocument,
  DirectiveType,
  DocumentType,
  SemanticClass,

  // Validation
  ValidationResult,
  ValidationError,
  ValidationSeverity,

  // Plugin types
  DirectiveProcessor,
  DirectiveMatch,

  // Requirements
  DocumentTypeRequirements,
} from "@markdownkit/remark-mdd/types";

Use Cases

markdownkit Integration

// .remarkrc.js
export default {
  plugins: [
    // ... other plugins
    (await import("@markdownkit/remark-mdd/plugins/document-structure"))
      .default,
    (await import("@markdownkit/remark-mdd/plugins/text-formatting")).default,
  ],
};

Custom Build Tool

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkMddDocumentStructure from "@markdownkit/remark-mdd/plugins/document-structure";
import remarkMddTextFormatting from "@markdownkit/remark-mdd/plugins/text-formatting";
import { validateDocument } from "@markdownkit/remark-mdd/validator";

async function processDocument(content) {
  // Validate first
  const validation = validateDocument(content);
  if (!validation.valid) {
    throw new Error(
      `Validation failed: ${validation.errors.map((e) => e.message).join(", ")}`,
    );
  }

  // Process with remark
  const result = await unified()
    .use(remarkParse)
    .use(remarkMddDocumentStructure)
    .use(remarkMddTextFormatting)
    .process(content);

  return String(result);
}

Anasa Knowledge Base Integration

import {
  remarkMddDocumentStructure,
  remarkMddTextFormatting,
} from "@markdownkit/remark-mdd";

// Add MDD support to your editor pipeline
editor.use(remarkMddDocumentStructure);
editor.use(remarkMddTextFormatting);

Document Types

MDD supports 54+ professional document types with type-specific validation:

business-letter, business-proposal, invoice, proposal, contract,
legal-contract, agreement, memorandum, memo, report, legal-notice,
legal-guide, terms-of-service, privacy-policy, nda,
employment-contract, purchase-order, quote, estimate, receipt,
statement, notice, certificate, affidavit, power-of-attorney,
will, trust, deed, lease, rental-agreement, service-agreement,
consulting-agreement, partnership-agreement, operating-agreement,
shareholder-agreement, articles-of-incorporation, bylaws,
resolution, minutes, policy, procedure, manual, guide,
specification, requirements, whitepaper, case-study, brief,
motion, complaint, answer, discovery, subpoena, summons,
warrant, order, judgment, decree, other

Each document type has specific required and recommended frontmatter fields and directives.

CLI Tools

For command-line usage with preview and validation tools, install the main package:

npm install -g @markdownkit/mdd

# Preview documents
mdd-preview document.mdd

# Validate documents
mdd-validate document.mdd

See @markdownkit/mdd for CLI documentation.

Documentation

• MDD Specification - Complete syntax reference
• Validation Guide - Comprehensive validation documentation
• Business Documents Catalog - 200+ document types analyzed

Related Packages

• @markdownkit/mdd - CLI tools for MDD (preview, validate)
• @markdownkit/markdownkit - Markdown linter/formatter with MDD support
• Anasa - Knowledge base with MDD integration (planned)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

License

MIT © Dominikos Pritis

Changelog

See CHANGELOG.md for version history.