Headless Wix blog SEO: CMS content strategy and rendering

The Wix Blog API provides rich content including posts, categories, tags, SEO metadata, author profiles, reading time, and featured images — everything you need to build a high-performance blog on a custom frontend. By decoupling the Wix CMS from the presentation layer, you gain full control over HTML semantics, schema markup, internal linking architecture, and page rendering strategy. This lesson walks through five comprehensive guides for building a headless Wix blog that outperforms the native Wix blog in search results. From paginated archives and breadcrumb schema to tag archives, related posts, and dynamic table of contents, every pattern here is production-ready and SEO-optimised.

Fetching Blog Content from the Wix Blog API

The Wix Blog API, accessed via the @wix/sdk package, returns structured post objects containing the title, slug, content in rich text format, SEO title, SEO description, featured image URL, publication date, last updated date, author information, categories array, tags array, and reading time estimate. You query this data server-side in your Next.js application during the getStaticProps or generateStaticParams phase, then render it as semantic HTML that search engines can fully crawl without executing JavaScript.

Each API response for a post list also includes total post count and cursor-based pagination tokens, which are essential for building properly paginated archive pages. For individual posts, the content field is returned as a Wix rich text document that you must parse into HTML. Use the @wix/ricos-viewer package or write a custom parser that produces clean semantic HTML with proper heading tags, blockquote elements, figure and figcaption for images, and meaningful anchor text for links rather than generic div-based output.

Setting up the Wix Blog API connection in Next.js

• Install the Wix SDK in your Next.js project: npm install @wix/sdk @wix/blog
• Create a Wix client singleton in lib/wix-client.ts using createClient() from @wix/sdk and import the blog module from @wix/blog
• Configure the client with your Wix site ID from the Wix dashboard under Settings > Business Info > Site ID
• In your blog list page (app/blog/page.tsx), call wixClient.blog.listPosts() with the fields parameter to request only the fields you need: title, slug, excerpt, coverImage, publishedDate, tags, categories, minutesToRead
• For individual post pages, use wixClient.blog.getPost(postId) to fetch the full post including the rich text content field
• Parse the rich text content using a custom renderRichText() function that maps Wix rich text nodes to semantic HTML elements
• Pass the structured post data to your page component as props so all content is available in the initial HTML response
• Generate static params for all posts at build time using generateStaticParams() that calls wixClient.blog.listPosts() with pagination until all slugs are collected
• Configure revalidate: 3600 in your fetch calls or use ISR with a 1-hour revalidation window so posts rebuild automatically when updated
• Set up a Wix webhook in your dashboard pointing to an /api/revalidate endpoint that triggers on-demand ISR rebuilds when posts are published or updated

Setting Up Pagination for Blog Archives

Pagination is essential for large blog archives. Without it, you either dump hundreds of posts on a single slow page or hide content from Google entirely. The Wix Blog API supports cursor-based pagination, but for SEO purposes you need to convert this into numbered page URLs (/blog/page/2, /blog/page/3) with proper rel="prev" and rel="next" link tags that tell Google how the archive is connected. Each paginated archive page should render full post excerpts rather than just titles, giving Google enough content to understand what each page covers.

Implementing SEO-friendly blog archive pagination

• Create the folder structure app/blog/page/[pageNumber]/page.tsx for numbered pagination URLs
• Define a POSTS_PER_PAGE constant (typically 12 for a grid layout or 10 for a list layout) and keep it consistent across the entire archive
• In generateStaticParams(), fetch the total post count from the Wix Blog API using wixClient.blog.listPosts({ limit: 1 }) and reading the total field from the response
• Calculate total pages as Math.ceil(totalPosts / POSTS_PER_PAGE) and generate page number params for all values from 1 to totalPages
• In the page component, calculate the offset as (pageNumber - 1) * POSTS_PER_PAGE and call wixClient.blog.listPosts({ limit: POSTS_PER_PAGE, offset: offset })
• Add rel="prev" and rel="next" link tags in your page metadata: on page 2, include prev pointing to /blog and next pointing to /blog/page/3
• On page 1 (/blog), include only a rel="next" tag pointing to /blog/page/2 — do not include a rel="prev" tag on the first page
• Add a canonical tag to each paginated page pointing to itself, not to the first page — Google treats each paginated page as a distinct indexable URL
• Render a visible page number indicator and prev/next navigation links styled consistently with your site design
• Add CollectionPage schema to each archive page with the numberOfItems, url, and name properties populated from your page data

Implementing Article and BreadcrumbList Schema

Blog posts are prime candidates for Article rich results in Google Search. To qualify, each post needs valid Article JSON-LD with the headline, author, datePublished, dateModified, image, and publisher fields. Combined with BreadcrumbList schema that mirrors your visible breadcrumb navigation, you give Google a complete structural picture of how your content is organised within the site hierarchy. Both schema types should be generated programmatically from your Wix API data, never hardcoded, so they stay accurate as content changes.

Building Article and BreadcrumbList schema for blog posts

• Create a lib/schema.ts file with pure functions that accept post data objects and return valid JSON-LD schema objects
• Write a buildArticleSchema(post) function that outputs the @context, @type: "Article", headline (max 110 chars), author (@type: "Person", name, url), datePublished (ISO 8601), dateModified, image (@type: "ImageObject" with url, width, height from Wix Media dimensions), and publisher (@type: "Organization" linking to your site)
• Write a buildBreadcrumbSchema(crumbs) function that accepts an array of { name, url } objects and outputs a BreadcrumbList with ListItem entries numbered from 1
• For a blog post at /blog/my-post-slug, create three breadcrumb entries: Home (position 1), Blog (position 2), and the post title (position 3)
• In your blog post page component, combine both schemas using the @graph pattern inside a single script tag: { "@context": "https://schema.org", "@graph": [articleSchema, breadcrumbSchema] }
• Set the image field to the Wix Media CDN URL of the featured image with explicit width and height parameters appended using Wix media transformation syntax
• Populate the author name and URL from the Wix post author data returned by the Blog API — link to an author archive page at /blog/author/[authorSlug]
• Include the publisher logo as an ImageObject nested inside the publisher Organisation object, using your site logo URL from Wix Media CDN
• Validate your implementation using the Google Rich Results Test at search.google.com/test/rich-results — check for both the Article and Breadcrumb test results
• Deploy and then monitor Google Search Console under Enhancements > Articles to confirm Google has indexed your Article rich results without errors

Building Tag and Category Archive Pages

Category and tag archive pages serve a dual purpose: they help users discover related content and they give Google topical cluster signals that strengthen your site authority around specific subjects. A category page for "Technical SEO" that links to fifteen well-written posts on technical SEO topics reinforces your topical authority far more than fifteen individual posts with no connecting hub. The Wix Blog API returns category and tag data with each post, and provides dedicated endpoints for listing all categories and tags across your blog.

Building category and tag archive pages with the Wix Blog API

• Create folder structures at app/blog/category/[categorySlug]/page.tsx and app/blog/tag/[tagSlug]/page.tsx for archive URL patterns
• In generateStaticParams() for categories, call wixClient.blog.listCategories() to fetch all categories and return their slugs as static params
• In generateStaticParams() for tags, call wixClient.blog.listTagsByPost() or query posts and extract unique tags by aggregating the tags arrays from all post responses
• On the category page component, call wixClient.blog.listPosts({ categoryIds: [categoryId] }) to fetch only posts in that category, with pagination support
• On the tag page component, call wixClient.blog.listPosts({ tagIds: [tagId] }) to filter posts by tag
• Render each post as a card with the post title, publication date, excerpt (150-200 characters), featured image thumbnail, and a "Read more" link to the full post
• Add a visible breadcrumb: Home > Blog > Category > [Category Name] with matching BreadcrumbList JSON-LD schema
• Write a unique introductory paragraph for each category page describing what topics the category covers — do not leave category pages with only a list of posts and no explanatory text
• Add CollectionPage JSON-LD schema with the category name as the name property and the total post count as numberOfItems
• Include a rel="canonical" tag on each category archive page pointing to itself to prevent any URL parameter variants from causing duplicate content issues
• Cross-link between related categories in a "Related Topics" section at the bottom of each category page to build internal linking between your topic clusters

Creating a Related Posts Widget with Internal Linking

Related posts widgets are one of the most underutilised internal linking tools in blog SEO. When a reader finishes an article about "Wix hreflang implementation," showing them three related posts about "international SEO" and "multilingual Wix sites" keeps them on your site longer and creates contextual internal links that pass authority and topical relevance signals between your posts. With headless Wix you can build this entirely server-side, so the links are in the HTML from the start and fully crawlable by Google without any JavaScript execution.

Implementing a server-rendered related posts widget

• In your blog post page component, identify the current post's categories and tags from the Wix API response
• Make a secondary Wix Blog API call to fetch posts sharing at least one category with the current post: wixClient.blog.listPosts({ categoryIds: currentPost.categoryIds, limit: 6 })
• Filter out the current post from the results using post.id !== currentPost.id to avoid linking a post to itself
• Score the remaining posts by relevance: give 2 points for each matching category and 1 point for each matching tag, then sort by total score descending
• Select the top 3 posts by relevance score as your related posts — if fewer than 3 posts share categories, fall back to recent posts from the same primary category
• Render the related posts section as an aside element positioned below the article body with the heading "Continue Reading" or "Related Articles"
• For each related post card, render the featured image (using Wix Media CDN URL with width=400&q=80 parameters), post title as a heading, excerpt of 100-120 characters, and publication date
• Wrap each related post card title in an anchor tag pointing to the headless blog post URL — these links are fully crawlable and pass PageRank between your posts
• Add aria-label attributes to each card link describing where it goes: aria-label="Read: [Post Title]" to improve accessibility and differentiate identical "Read more" link text
• Track clicks on related posts using your analytics platform to measure engagement lift — posts with well-matched related posts typically see 15-25% lower bounce rates

Implementing Table of Contents from H2 Headings

A table of contents generated from the H2 headings in your blog post serves two SEO purposes: it improves user experience by letting readers jump to sections, and it creates anchor link targets that appear in Google Search as sitelinks beneath your listing for longer, comprehensive posts. On headless Wix, you generate the table of contents server-side by parsing the rich text content from the Wix Blog API before rendering it — no JavaScript or DOM manipulation needed at runtime.

Building a server-side table of contents from Wix rich text content

• Write a extractHeadings(richTextContent) function that iterates through the Wix rich text node tree and collects all nodes where the node type is "heading" with level 2
• For each H2 heading node, extract the plain text content by joining the text values of all child text nodes, stripping any formatting marks
• Generate a URL-friendly anchor ID from each heading text using a slugify function: lowercase, replace spaces with hyphens, remove special characters
• Return an array of { id, text } objects representing the ordered list of H2 headings with their anchor IDs
• In your rich text HTML renderer, when outputting H2 elements, add the matching id attribute: <h2 id="[generatedId]"> so the anchor links resolve to the correct position
• Render the table of contents as a nav element with role="navigation" and aria-label="Table of contents" positioned after the article introduction and before the first H2
• Inside the nav, use an ordered list (ol) where each item is an anchor link pointing to #[generatedId] with the heading text as the visible link text
• Add scroll-margin-top CSS to all H2 elements (e.g., scroll-margin-top: 80px) to account for sticky headers so anchor links land at the correct visual position
• Only render the table of contents component if the post has 3 or more H2 headings — shorter posts with 1-2 H2s do not benefit from a table of contents
• Add JSON-LD TableOfContents markup (as part of your Article schema) using the hasPart property listing each section with its URL and name to provide explicit structure signals to Google

Rich Text Rendering and Semantic HTML

The Wix Blog API returns post content as a proprietary rich text node tree, not as raw HTML. This means you must write or use a parser that converts Wix rich text nodes into valid, semantic HTML. The quality of this rendering directly affects your SEO: a parser that wraps everything in generic div elements will produce content Google reads as structureless blocks of text. A parser that outputs proper heading hierarchies, blockquotes, figure elements for images with figcaption, and clean paragraph tags produces content Google can fully interpret and index with high quality signals.

• Map heading nodes to the correct HTML heading level (h2, h3, h4) based on the node's level property, never render all headings as the same tag
• Map paragraph nodes to p elements — avoid wrapping paragraphs in div elements as this breaks semantic structure
• Map blockquote nodes to blockquote elements with optional cite attribute if a source is provided
• Map image nodes to figure elements containing an img tag with the Wix Media CDN URL, explicit width, height, and alt text from the image node data
• Map list nodes to ul or ol elements with li children based on whether the list type is unordered or ordered
• Map code block nodes to pre and code elements with the language class set from the node's language attribute for syntax highlighting
• Map link nodes to anchor elements with descriptive text — never render the bare URL as the link text
• Map divider nodes to hr elements, not decorative div elements, so the break is semantically meaningful
• Strip any nodes or attributes that produce empty elements — empty p tags, headings with no text, or images with missing src values all reduce content quality
• Preserve the original heading hierarchy from the Wix editor — if an author used H3 after H2, render it exactly that way rather than normalising all subheadings to H3