@marvalt/wparser (WordPress Pages Parser)

Static-only WordPress page parser and renderer for React apps.

• Input: Gutenberg blocks from static JSON
• Output: React components styled via your theme
• No live refresh; static data only
• Auto-hero uses featured image unless [HEROSECTION] is present
• Extensible: future adapters (Elementor/Divi) via registry

Documentation

Comprehensive documentation is available in the docs/ folder:

• STYLING.md - How WordPress and applications control styling
• COLOR_MAPPING.md - Color mapping system for background colors
• SPACING.md - Spacing system and customization
• CUSTOMIZATION.md - Complete customization guide

Installation

Peer deps: React 18+

npm install
npm run build -w digivalt-npm-packages/marvalt-wparser

Security

• Content is rendered as text; no HTML is injected by default.
• If you enable any HTML rendering in custom renderers, sanitize first and use a CSP.
• Use trusted WordPress sources; this package assumes trusted input for v0.1.0.

Data shape (required)

• Gutenberg blocks only (no HTML fallback in v0.1.0)
• Minimal page type:

interface WordPressPageMinimal {
  id: number;
  slug: string;
  title?: { rendered: string };
  blocks: Array<{
    name: string;
    attributes?: Record<string, unknown>;
    innerBlocks?: any[];
    innerHTML?: string;
  }>;
  _embedded?: { 'wp:featuredmedia'?: Array<{ source_url?: string; alt_text?: string }> };
}

Usage

import { WPContent, WPPage, createDefaultRegistry, WPErrorBoundary } from '@marvalt/wparser';

const registry = createDefaultRegistry();

<WPErrorBoundary>
  <WPPage page={page} registry={registry} />
</WPErrorBoundary>

<WPContent blocks={page.blocks} registry={registry} />

Supported core blocks (default registry)

• paragraph, heading, image, list, list-item, group, columns, column, separator, buttons/button, quote, code, preformatted, table (+ row/cell)
• cover - Hero sections with background images, overlays, and inner content
• media-text - Side-by-side media and text layouts with responsive stacking

Custom renderers

Extend or replace mappings:

const registry = createDefaultRegistry();
registry.renderers['core/paragraph'] = ({ block }) => <p className="my-2">{String(block.attributes?.content || '')}</p>;

API

• parseGutenbergBlocks(blocks) → returns normalized block tree
• renderNodes(blocks, registry, { debugWrappers? }) → React nodes
• createDefaultRegistry() → default mapping
• WPContent, WPPage components
• WPErrorBoundary

Notes

• No environment handling in v0.1.0.
• Tailwind classes are used in defaults; replace or override as needed.

Roadmap

• Shortcodes/embeds/ACF plugins
• Optional adapters: Elementor, Divi (as separate packages)
• Error boundary customization and logging hooks