Article: Create and Publish Blog Posts with Rich Content and Images

Article URL: https://dev.wix.com/docs/kb-only/MCP_REST_RECIPES_KB_ID/TRAIN_how-to-create-a-blog-post

Description

This article demonstrates how to create and immediately publish blog posts using Wix Blog application, including handling external images, rich content formatting, and proper media management workflow.

IMPORTANT: Use the Wix SDK rather than direct API calls whenever possible

Part 1: Import External Images to Wix Media Manager

1. Identify external image URLs from user input for cover images and embedded content images.

2. Import each external image using Import File (SDK | REST). This converts external URLs to Wix Media IDs required for blog posts.

   import { files } from '@wix/media';
   
   const importResult = await files.importFile({
     url: 'https://example.com/image.jpg',
     mediaType: files.MediaType.IMAGE,
     displayName: 'Cover Image.jpg'
   });
   const mediaId = importResult.file.id; // Use this ID in blog post
   

3. Store the returned file IDs for use in blog post creation. Images with operationStatus: "PENDING" can be used immediately.

Part 2: Create Blog Post with Rich Content

1. Create blog post using Create Draft Post (SDK | REST) for single posts, or Bulk Create Draft Posts (SDK | REST) for multiple posts.

   import { draftPosts } from '@wix/blog';
   
   const result = await draftPosts.createDraftPost({
     draftPost: {
       title: 'My Blog Post',
       memberId: 'author-member-id',
       richContent: ricosContent,
       media: {
         wixMedia: {
           image: { id: mediaId }
         },
         displayed: true,
         custom: true
       }
     },
     publish: true
   });
   

2. Structure rich content using Ricos JSON format. Reference Ricos documentation for complete node structure. Common node types:

   • PARAGRAPH for text content
   • HEADING for section headers
   • IMAGE for embedded images (requires Wix Media ID)
   • ORDERED_LIST and BULLETED_LIST for lists
   • BLOCKQUOTE for quoted text
   • LIST_ITEM for individual list items

   CRITICAL: All TEXT nodes MUST be wrapped in PARAGRAPH nodes within their parent containers.

   const ricosContent = {
     nodes: [
       {
         type: 'PARAGRAPH',
         nodes: [{
           type: 'TEXT',
           textData: {
             text: 'This is a paragraph with some content.',
             decorations: []
           }
         }],
         paragraphData: {}
       }
     ]
   };
   

   Correct BLOCKQUOTE structure:

   {
     type: 'BLOCKQUOTE',
     nodes: [
       {
         type: 'PARAGRAPH',  // TEXT nodes must be in PARAGRAPH
         nodes: [
           {
             type: 'TEXT',
             textData: { text: 'Quote text here', decorations: [] }
           }
         ],
         paragraphData: {}
       }
     ],
     blockquoteData: { indentation: 1 }
   }
   

   Correct LIST_ITEM structure:

   {
     type: 'LIST_ITEM',
     nodes: [
       {
         type: 'PARAGRAPH',  // TEXT nodes must be in PARAGRAPH
         nodes: [
           {
             type: 'TEXT',
             textData: { text: 'List item text', decorations: [] }
           }
         ],
         paragraphData: {}
       }
     ]
   }
   

3. For embedded images in rich content, use IMAGE nodes with Wix Media IDs:

   const imageNode = {
     type: 'IMAGE',
     nodes: [],
     imageData: {
       containerData: {
         width: { size: 'CONTENT' },
         alignment: 'CENTER'
       },
       image: {
         src: { id: mediaId }, // Use imported media ID
         width: 900,
         height: 600
       },
       altText: 'Descriptive alt text'
     }
   };
   

4. Set publish: true to immediately publish the post rather than saving as draft.

Part 3: Handle Categories and Tags (Optional)

1. Resolve category IDs using List Categories (SDK | REST) if user provides category names.

2. Resolve tag IDs using Query Tags (SDK | REST) if user provides tag labels.

3. Include resolved IDs in categoryIds and tagIds arrays in the draft post object.

IMPORTANT NOTES:

• Never mock blog posts or media IDs - always use the APIs to import images and create posts
• When using the Wix SDK, do not initialize the Wix Client in this process - it should be configured beforehand
• Always read the full documentation of methods before implementation
• If writing JavaScript/TypeScript code, use the SDK and ensure @wix/blog and @wix/media packages are in project dependencies
• Never guess types - use types from @wix/blog and @wix/media packages
• External images MUST be imported via Import File API before use in blog posts - direct external URLs will not work
• For 3rd-party app integrations, memberId is mandatory - use List Members API if needed to get member ID
• Use ONLY the file ID (without wix:image://v1/ prefix) for both cover images and embedded images
• Rich content IMAGE nodes require both width and height properties in the image object
• Images with "operationStatus": "PENDING" from import can be used immediately in blog posts
• Set publish: true in the request to publish immediately rather than save as draft
• For multiple posts, use Bulk Create Draft Posts API with draftPosts array
• Include fieldsets: ['URL'] to get post URLs in the response
• Handle image import failures gracefully - continue without images if import fails
• Provide meaningful displayName values during image import for better organization
• Use appropriate Ricos node types (PARAGRAPH, HEADING, LIST, etc.) for semantic content structure
• Consider batching image imports when creating multiple posts with many images

CRITICAL RICOS JSON STRUCTURE RULES:

• NEVER place TEXT nodes directly in BLOCKQUOTE, LIST_ITEM, or other container nodes
• ALL TEXT nodes MUST be wrapped in PARAGRAPH nodes within their parent containers
• BLOCKQUOTE nodes must contain PARAGRAPH nodes, which contain TEXT nodes
• LIST_ITEM nodes must contain PARAGRAPH nodes, which contain TEXT nodes
• Failure to follow proper nesting will result in parsing errors: "Expected a paragraph node but found TEXT"
• Always validate Ricos structure before sending to ensure TEXT nodes are properly nested