/wix-manage

Rich Content (Ricos) Converter Service

This recipe covers how to validate and convert content between Ricos documents (Wix's rich content format) and other formats like HTML, Markdown, and plain text.

Overview

Ricos is Wix's rich content format used across various Wix applications (Blog, Stores, etc.). The Ricos Documents API provides:

• Validation: Check if a document conforms to the Ricos format
• Convert to Ricos: Transform HTML, Markdown, or plain text into a Ricos document
• Convert from Ricos: Transform a Ricos document back to HTML, Markdown, or plain text

Learn more about Rich Content and Ricos document structure.

Required API Endpoints

Available Plugins

Plugins determine which content types are recognized when validating or converting. Specify them as uppercase enum values:

IMPORTANT NOTES:

• Plugin values must be UPPERCASE enum strings (e.g., "HEADING", not "heading")
• Content using unsupported plugins will result in validation violations
• When converting HTML, only elements matching your plugins are converted

Step 1: Validate a Ricos Document

Check if a document conforms to the Ricos format and optionally fix issues.

Endpoint: POST https://www.wixapis.com/ricos/v1/ricos-document/validate (docs)

Request Body:

{
  "document": {
    "nodes": [
      {
        "type": "PARAGRAPH",
        "id": "p1",
        "nodes": [
          {
            "type": "TEXT",
            "id": "t1",
            "textData": {
              "text": "Hello World",
              "decorations": []
            }
          }
        ],
        "paragraphData": {}
      }
    ]
  },
  "plugins": ["HEADING", "LINK", "IMAGE", "TEXT_COLOR"],
  "fixDocument": true
}

Response:

{
  "valid": true,
  "violations": [],
  "validDocument": {
    "nodes": [
      {
        "type": "PARAGRAPH",
        "id": "p1",
        "nodes": [
          {
            "type": "TEXT",
            "id": "t1",
            "textData": {
              "text": "Hello World",
              "decorations": []
            }
          }
        ],
        "paragraphData": {}
      }
    ]
  }
}

Step 2: Convert HTML to Ricos

Transform HTML content into Ricos document format.

Endpoint: POST https://www.wixapis.com/ricos/v1/ricos-document/convert/to-ricos (docs)

Request Body:

{
  "html": "<h1>Welcome</h1><p>This is a <strong>bold</strong> paragraph with a <a href=\"https://example.com\">link</a>.</p>",
  "options": {
    "plugins": ["HEADING", "LINK", "TEXT_COLOR", "TEXT_HIGHLIGHT"]
  }
}

Response:

{
  "document": {
    "nodes": [
      {
        "type": "HEADING",
        "id": "",
        "headingData": { "level": 1 },
        "nodes": [
          { "type": "TEXT", "textData": { "text": "Welcome", "decorations": [] } }
        ]
      },
      {
        "type": "PARAGRAPH",
        "id": "",
        "nodes": [
          { "type": "TEXT", "textData": { "text": "This is a ", "decorations": [] } },
          { "type": "TEXT", "textData": { "text": "bold", "decorations": [{ "type": "BOLD", "fontWeightValue": 700 }] } },
          { "type": "TEXT", "textData": { "text": " paragraph with a ", "decorations": [] } },
          { "type": "TEXT", "textData": { "text": "link", "decorations": [{ "type": "LINK", "linkData": { "link": { "url": "https://example.com", "target": "SELF" } } }] } },
          { "type": "TEXT", "textData": { "text": ".", "decorations": [] } }
        ]
      }
    ],
    "metadata": { "version": 1 }
  }
}

Step 3: Convert Markdown to Ricos

Uses the same endpoint as HTML conversion, with markdown instead of html.

Request Body:

{
  "markdown": "# Welcome\n\nThis is a **bold** paragraph with a [link](https://example.com).",
  "options": {
    "plugins": ["HEADING", "LINK", "CODE_BLOCK"]
  }
}

Step 4: Convert Plain Text to Ricos

Request Body:

{
  "plainText": "This is plain text content.\n\nIt will be converted to paragraphs.",
  "options": {
    "plugins": []
  }
}

Step 5: Convert Ricos to HTML / Markdown / Plain Text

Convert a Ricos document back to another format.

Endpoint: POST https://www.wixapis.com/ricos/v1/ricos-document/convert/from-ricos (docs)

Request Body (to HTML):

{
  "document": {
    "nodes": [
      {
        "type": "HEADING",
        "id": "h1",
        "headingData": { "level": 1 },
        "nodes": [
          { "type": "TEXT", "id": "t1", "textData": { "text": "Welcome", "decorations": [] } }
        ]
      },
      {
        "type": "PARAGRAPH",
        "id": "p1",
        "nodes": [
          { "type": "TEXT", "id": "t2", "textData": { "text": "Hello world with ", "decorations": [] } },
          { "type": "TEXT", "id": "t3", "textData": { "text": "bold", "decorations": [{ "type": "BOLD", "fontWeightValue": 700 }] } }
        ],
        "paragraphData": {}
      }
    ]
  },
  "targetFormat": "HTML"
}

Response:

{
  "html": "<h1>Welcome</h1><p>Hello world with <span style=\"font-weight: 700\">bold</span></p>"
}

Target format options: "HTML", "MARKDOWN", "PLAIN_TEXT"

For plain text, you can include optional settings:

{
  "document": { "nodes": [...] },
  "targetFormat": "PLAIN_TEXT",
  "plainTextOptions": {
    "includeLinks": true,
    "includeMediaLinks": true
  }
}

Common Use Cases

Blog Post Content Import

When importing blog content from external sources:

1. Convert HTML/Markdown to Ricos format using Convert To Ricos
2. Validate the converted document with fixDocument: true
3. Use the validated document in the Blog Posts API

Rich Content Validation Before Saving

Before saving rich content:

1. Validate with fixDocument: true
2. Use the returned validDocument for saving
3. Check violations array for any issues

Round-Trip Conversion

Convert between formats for editing workflows:

1. Convert Ricos to Markdown for a Markdown editor
2. Convert edited Markdown back to Ricos for storage
3. See Sample Flows for a detailed example

Gotchas & Troubleshooting

• Maximum content length: 10,000 characters for HTML, Markdown, or plain text
• Plugin limits: Maximum 100 plugins per request
• Plugin name max length: 30 characters
• If converting HTML with images but IMAGE plugin not specified, images are silently dropped
• Always validate converted content before using in production
• The plain text convert/from-ricos response concatenates text without separators between nodes — use includeLinks: true in plainTextOptions if you need link URLs preserved