markdown-to-wix-ricos

A TypeScript library for converting Markdown to Wix Ricos format. This package allows you to transform standard Markdown content into the rich content format used by Wix's Ricos editor.

Features

• 🚀 Full TypeScript support with comprehensive type definitions
• 📝 Complete Markdown support including headings, paragraphs, lists, images, links, code blocks, and more
• 🎨 Customizable conversion options for fine-tuning the output
• 🔧 Flexible API with both simple functions and class-based converters
• ✅ Comprehensive testing with high test coverage
• 📊 Built-in analysis tools for markdown content inspection
• 🛡️ Error handling with detailed error messages and validation

Installation

npm install markdown-to-wix-ricos

Quick Start

Simple Conversion

import { markdownToRicos } from 'markdown-to-wix-ricos';

const markdown = `# Hello World

This is a **bold** paragraph with *italic* text.

- List item 1
- List item 2

![Image](https://example.com/image.jpg)`;

const ricosDocument = markdownToRicos(markdown);
console.log(JSON.stringify(ricosDocument, null, 2));

With Custom Options

import { markdownToRicos, ConversionOptions } from 'markdown-to-wix-ricos';

const options: Partial<ConversionOptions> = {
  baseUrl: 'https://my-site.com',
  defaultImageAlignment: 'LEFT',
  defaultImageWidth: 'FULL_WIDTH',
  maxHeadingLevel: 4,
  generateIds: true
};

const ricosDocument = markdownToRicos(markdown, options);

API Reference

Functions

markdownToRicos(markdown: string, options?: Partial<ConversionOptions>): RicosDocument

Converts markdown text to Wix Ricos format.

Parameters:

• markdown - The markdown text to convert
• options - Optional conversion options

Returns: A complete Ricos document object

markdownToRicosWithAnalysis(markdown: string, options?: Partial<ConversionOptions>)

Converts markdown and provides detailed analysis information.

Returns: An object containing both the converted document and analysis data:

{
  document: RicosDocument;
  analysis: {
    originalMarkdown: string;
    tokenCount: number;
    nodeCount: number;
    conversionTime: number;
    warnings: string[];
  };
}

validateMarkdown(markdown: string)

Validates markdown content before conversion.

Returns: Validation result with errors and warnings:

{
  valid: boolean;
  errors: string[];
  warnings: string[];
}

Classes

MarkdownToRicosConverter

A reusable converter class for multiple conversions with the same options.

import { MarkdownToRicosConverter } from 'markdown-to-wix-ricos';

const converter = new MarkdownToRicosConverter({
  generateIds: true,
  defaultImageAlignment: 'CENTER'
});

const doc1 = converter.convert('# First Document');
const doc2 = converter.convert('# Second Document');

// Update options
converter.updateOptions({ maxHeadingLevel: 3 });

Conversion Options

interface ConversionOptions {
  // Generate unique IDs for nodes (default: true)
  generateIds?: boolean;
  
  // Base URL for relative image links
  baseUrl?: string;
  
  // Default image alignment (default: 'CENTER')
  defaultImageAlignment?: 'CENTER' | 'LEFT' | 'RIGHT';
  
  // Default image width (default: 'CONTENT')
  defaultImageWidth?: 'CONTENT' | 'SMALL' | 'ORIGINAL' | 'FULL_WIDTH';
  
  // Enable text wrapping around images (default: true)
  enableImageTextWrap?: boolean;
  
  // Custom node ID prefix (default: 'node')
  nodeIdPrefix?: string;
  
  // Maximum heading level to convert (default: 6)
  maxHeadingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
  
  // Preserve code block language info (default: true)
  preserveCodeLanguage?: boolean;
  
  // Default text alignment (default: 'AUTO')
  defaultTextAlignment?: 'AUTO' | 'LEFT' | 'RIGHT' | 'CENTER' | 'JUSTIFY';
}

Supported Markdown Elements

| Markdown Element | Ricos Node Type | Notes | |------------------|-----------------|-------| | # Heading | HEADING | Supports levels 1-6 | | Paragraph | PARAGRAPH | Basic text content | | **Bold** | Text with BOLD decoration | Font weight styling | | *Italic* | Text with ITALIC decoration | Italic styling | | [Link](url) | Text with LINK decoration | External and internal links | | ![Image](url) | IMAGE | With optional captions | | - List item | BULLETED_LIST | Unordered lists | | 1. List item | ORDERED_LIST | Ordered lists | | > Quote | BLOCKQUOTE | Block quotes | | `code` | Text content | Inline code (as text) | | ```code``` | CODE_BLOCK | Code blocks with language | | --- | DIVIDER | Horizontal rules |

Examples

Basic Usage

import { markdownToRicos } from 'markdown-to-wix-ricos';

// Simple paragraph
const simple = markdownToRicos('Hello, **world**!');

// Complex document
const complex = markdownToRicos(`
# My Blog Post

This is the introduction paragraph with [a link](https://example.com).

## Features

- Feature 1
- Feature 2 with **emphasis**
- Feature 3

> This is an important quote from someone famous.

Here's some code:

\`\`\`javascript
function hello() {
  console.log('Hello, world!');
}
\`\`\`

![Hero Image](https://example.com/hero.jpg "A beautiful hero image")

---

*Thank you for reading!*
`);

Advanced Usage with Analysis

import { markdownToRicosWithAnalysis, validateMarkdown } from 'markdown-to-wix-ricos';

const markdown = '# Title\n\nContent with ![image](img.jpg)';

// Validate first
const validation = validateMarkdown(markdown);
if (!validation.valid) {
  console.error('Validation errors:', validation.errors);
  return;
}

// Convert with analysis
const result = markdownToRicosWithAnalysis(markdown, {
  baseUrl: 'https://my-cdn.com',
  defaultImageWidth: 'FULL_WIDTH'
});

console.log('Conversion completed in', result.analysis.conversionTime, 'ms');
console.log('Generated', result.analysis.nodeCount, 'nodes');
console.log('Warnings:', result.analysis.warnings);

// Use the document
const ricosDocument = result.document;

Using the Converter Class

import { MarkdownToRicosConverter } from 'markdown-to-wix-ricos';

// Create a converter with specific options
const converter = new MarkdownToRicosConverter({
  generateIds: true,
  baseUrl: 'https://my-site.com',
  defaultImageAlignment: 'LEFT',
  nodeIdPrefix: 'blog'
});

// Convert multiple documents
const posts = [
  '# Post 1\n\nContent 1',
  '# Post 2\n\nContent 2',
  '# Post 3\n\nContent 3'
];

const ricosDocuments = posts.map(post => converter.convert(post));

// Analyze content
const analysis = converter.analyze('# Sample\n\nWith **bold** text');
console.log('Found', analysis.headingCount, 'headings');

Error Handling

The library provides detailed error information for debugging:

import { markdownToRicos, MarkdownConversionError } from 'markdown-to-wix-ricos';

try {
  const result = markdownToRicos(invalidMarkdown);
} catch (error) {
  if (error instanceof MarkdownConversionError) {
    console.error('Conversion failed:', error.message);
    console.error('Token:', error.token);
    console.error('Context:', error.context);
  }
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the project
npm run build

# Lint code
npm run lint

License

MIT License - see the LICENSE file for details.

Related

• Wix Ricos Documentation
• Markdown-it Parser

Changelog

1.0.0

• Initial release
• Full Markdown to Ricos conversion support
• TypeScript type definitions
• Comprehensive test suite
• Documentation and examples