+ GET
+
+
+## Authentication
+
+The endpoint respects WordPress's built-in REST API permissions:
+
+- **Published posts**: Publicly accessible (no authentication required)
+- **Draft/private posts**: Requires authentication and appropriate capabilities
+- **Custom post types**: Must have `show_in_rest` enabled
+
+## Parameters
+
+### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `post_id` | integer | Yes | The ID of the post to retrieve blocks from |
+
+### Query Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `include` | string | No | Comma-separated list of block types to include. Acts as an allowlist. |
+| `exclude` | string | No | Comma-separated list of block types to exclude. Acts as a blocklist. |
+
+:::warning
+You cannot use both `include` and `exclude` parameters simultaneously. The API will return an error if both are provided.
+:::
+
+## Response Format
+
+### Success Response
+
+```json
+{
+ "blocks": [
+ {
+ "name": "core/heading",
+ "attributes": {
+ "level": 2,
+ "content": "Welcome"
+ },
+ "innerBlocks": []
+ }
+ ]
+}
+```
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `blocks` | array | Array of block objects with nested structure |
+| `blocks[].name` | string | The block type (e.g., `core/paragraph`) |
+| `blocks[].attributes` | object | Block attributes as key-value pairs |
+| `blocks[].innerBlocks` | array | Nested blocks (recursive structure) |
+
+## Examples
+
+### Basic Request
+
+Fetch all blocks from post ID 123:
+
+```bash
+curl https://example.com/wp-json/vip-block-data-api/v1/posts/123/blocks
+```
+
+### JavaScript (Fetch API)
+
+```javascript
+async function fetchBlocks(postId) {
+ const response = await fetch(
+ `https://example.com/wp-json/vip-block-data-api/v1/posts/${postId}/blocks`
+ );
+
+ if (!response.ok) {
+ throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+ }
+
+ const data = await response.json();
+ return data.blocks;
+}
+
+// Usage
+fetchBlocks(123)
+ .then(blocks => {
+ console.log('Fetched blocks:', blocks);
+ })
+ .catch(error => {
+ console.error('Error fetching blocks:', error);
+ });
+```
+
+### WordPress API Client
+
+Using the `@wordpress/api-fetch` package:
+
+```javascript
+import apiFetch from '@wordpress/api-fetch';
+
+apiFetch({
+ path: '/vip-block-data-api/v1/posts/123/blocks'
+})
+ .then(data => {
+ console.log('Blocks:', data.blocks);
+ })
+ .catch(error => {
+ console.error('Error:', error);
+ });
+```
+
+### Include Specific Blocks
+
+Only fetch paragraphs and headings:
+
+```bash
+curl "https://example.com/wp-json/vip-block-data-api/v1/posts/123/blocks?include=core/paragraph,core/heading"
+```
+
+```javascript
+const blocks = await fetchBlocks(123, {
+ include: ['core/paragraph', 'core/heading']
+});
+
+function fetchBlocks(postId, options = {}) {
+ const params = new URLSearchParams();
+
+ if (options.include) {
+ params.append('include', options.include.join(','));
+ }
+
+ return fetch(
+ `https://example.com/wp-json/vip-block-data-api/v1/posts/${postId}/blocks?${params}`
+ ).then(res => res.json());
+}
+```
+
+### Exclude Specific Blocks
+
+Exclude embed blocks from the response:
+
+```bash
+curl "https://example.com/wp-json/vip-block-data-api/v1/posts/123/blocks?exclude=core/embed,core/html"
+```
+
+```javascript
+const blocks = await fetchBlocks(123, {
+ exclude: ['core/embed', 'core/html']
+});
+```
+
+### With Authentication
+
+For draft or private posts:
+
+```javascript
+import apiFetch from '@wordpress/api-fetch';
+
+// Set up authentication (nonce is automatically handled in WordPress context)
+const blocks = await apiFetch({
+ path: '/vip-block-data-api/v1/posts/123/blocks',
+ headers: {
+ 'X-WP-Nonce': wpApiSettings.nonce // From wp_localize_script
+ }
+});
+```
+
+Using basic authentication (not recommended for production):
+
+```bash
+curl -u username:password \
+ https://example.com/wp-json/vip-block-data-api/v1/posts/123/blocks
+```
+
+## Response Examples
+
+### Simple Post
+
+**Post Content:**
+```html
+
+/wp-json/vip-block-data-api/v1/posts/{post_id}/blocks
+About Us
+ + + +We are a great company.
+ +``` + +**API Response:** +```json +{ + "blocks": [ + { + "name": "core/heading", + "attributes": { + "level": 2, + "content": "About Us" + }, + "innerBlocks": [] + }, + { + "name": "core/paragraph", + "attributes": { + "content": "We are a great company.", + "dropCap": false + }, + "innerBlocks": [] + } + ] +} +``` + +### Nested Blocks + +**Post Content:** +```html + +
+
+
+
+```
+
+**API Response:**
+```json
+{
+ "blocks": [
+ {
+ "name": "core/columns",
+ "attributes": {},
+ "innerBlocks": [
+ {
+ "name": "core/column",
+ "attributes": {},
+ "innerBlocks": [
+ {
+ "name": "core/paragraph",
+ "attributes": {
+ "content": "Left column"
+ },
+ "innerBlocks": []
+ }
+ ]
+ },
+ {
+ "name": "core/column",
+ "attributes": {},
+ "innerBlocks": [
+ {
+ "name": "core/paragraph",
+ "attributes": {
+ "content": "Right column"
+ },
+ "innerBlocks": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
+```
+
+### Image Block
+
+**API Response:**
+```json
+{
+ "blocks": [
+ {
+ "name": "core/image",
+ "attributes": {
+ "id": 456,
+ "sizeSlug": "large",
+ "url": "https://example.com/wp-content/uploads/2024/01/image.jpg",
+ "alt": "Description of image",
+ "caption": "Image caption",
+ "width": 1024,
+ "height": 768
+ },
+ "innerBlocks": []
+ }
+ ]
+}
+```
+
+:::info
+The `width` and `height` attributes are automatically added by the plugin based on the image dimensions.
+:::
+
+### Custom Block
+
+**API Response:**
+```json
+{
+ "blocks": [
+ {
+ "name": "my-plugin/hero-banner",
+ "attributes": {
+ "title": "Welcome to Our Site",
+ "subtitle": "We build amazing things",
+ "backgroundImage": "https://example.com/bg.jpg",
+ "ctaText": "Get Started",
+ "ctaUrl": "/signup"
+ },
+ "innerBlocks": []
+ }
+ ]
+}
+```
+
+## Error Handling
+
+### Error Response Format
+
+```json
+{
+ "code": "rest_post_invalid_id",
+ "message": "Invalid post ID.",
+ "data": {
+ "status": 404
+ }
+}
+```
+
+### Common Error Codes
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `rest_post_invalid_id` | 404 | Post ID doesn't exist |
+| `rest_forbidden` | 403 | You don't have permission to view this post |
+| `rest_no_route` | 404 | Invalid endpoint URL |
+| `vip-block-data-api-no-blocks` | 200* | Post has no block content (warning, not error) |
+
+*Note: "No blocks" returns 200 OK with a warning in the response.
+
+### Handling Errors in JavaScript
+
+```javascript
+async function fetchBlocksSafely(postId) {
+ try {
+ const response = await fetch(
+ `https://example.com/wp-json/vip-block-data-api/v1/posts/${postId}/blocks`
+ );
+
+ const data = await response.json();
+
+ if (!response.ok) {
+ // Handle HTTP error
+ throw new Error(data.message || `HTTP ${response.status}`);
+ }
+
+ // Check for warnings
+ if (data.warnings && data.warnings.length > 0) {
+ console.warn('API warnings:', data.warnings);
+ }
+
+ return data.blocks;
+
+ } catch (error) {
+ console.error('Failed to fetch blocks:', error);
+ return [];
+ }
+}
+```
+
+## Caching
+
+### WordPress VIP
+
+On WordPress VIP, responses are automatically cached for **1 minute** using the platform's caching layer.
+
+Cache key includes:
+- Post ID
+- Include/exclude parameters
+- User permissions
+
+### Custom Caching
+
+Implement your own caching layer:
+
+```javascript
+class BlockCache {
+ constructor(ttl = 60000) { // 1 minute default
+ this.cache = new Map();
+ this.ttl = ttl;
+ }
+
+ get(key) {
+ const item = this.cache.get(key);
+ if (!item) return null;
+
+ if (Date.now() > item.expiry) {
+ this.cache.delete(key);
+ return null;
+ }
+
+ return item.data;
+ }
+
+ set(key, data) {
+ this.cache.set(key, {
+ data,
+ expiry: Date.now() + this.ttl
+ });
+ }
+}
+
+const cache = new BlockCache();
+
+async function fetchBlocksCached(postId) {
+ const cacheKey = `blocks-${postId}`;
+ const cached = cache.get(cacheKey);
+
+ if (cached) {
+ return cached;
+ }
+
+ const blocks = await fetchBlocks(postId);
+ cache.set(cacheKey, blocks);
+
+ return blocks;
+}
+```
+
+## Performance Considerations
+
+### Parse Time Threshold
+
+The plugin tracks parsing time and logs an error if it exceeds a threshold (default: 500ms on VIP).
+
+You can customize this threshold:
+
+```php
+define( 'WPCOMVIP__BLOCK_DATA_API__PARSE_TIME_ERROR_MS', 1000 ); // 1 second
+```
+
+### Best Practices
+
+1. **Cache responses** - Don't fetch on every request
+2. **Use include/exclude** - Reduce payload size by filtering blocks
+3. **Paginate content** - For posts with many blocks, consider pagination
+4. **Monitor performance** - Track API response times
+
+## Next Steps
+
+- [Response Format Details](./response-format)
+- [GraphQL API](./graphql-api)
+- [Filtering Blocks](../guides/block-filtering)
+- [React Renderer Example](../examples/react-renderer)
diff --git a/docs/docs/examples/filtering-blocks.md b/docs/docs/examples/filtering-blocks.md
new file mode 100644
index 0000000..5a7419c
--- /dev/null
+++ b/docs/docs/examples/filtering-blocks.md
@@ -0,0 +1,58 @@
+---
+sidebar_position: 4
+---
+
+# Filtering Blocks Examples
+
+Comprehensive examples of filtering blocks using various methods.
+
+## Server-Side Filtering
+
+### Exclude Security-Sensitive Blocks
+
+```php
+add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) {
+ $excluded = [ 'core/html', 'core/code', 'core/shortcode' ];
+ return ! in_array( $block_name, $excluded, true );
+}, 10, 3 );
+```
+
+### Content-Based Filtering
+
+```php
+add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) {
+ // Exclude images without alt text
+ if ( $block_name === 'core/image' ) {
+ return ! empty( $block['attrs']['alt'] ?? '' );
+ }
+ return $is_allowed;
+}, 10, 3 );
+```
+
+## Client-Side Filtering
+
+### React Component
+
+```jsx
+function FilteredContent({ blocks, allowedTypes }) {
+ const filteredBlocks = useMemo(() => {
+ return filterByType(blocks, allowedTypes);
+ }, [blocks, allowedTypes]);
+
+ return
+
+
+
+
+
+ Left column
+ +
+
+
+
+Right column
+ +Loading...
; + if (error) returnError: {error.message}
; + + const blocks = transformGraphQLBlocks(data.post.blocksDataV2); + + return ( +{data.post.title}
+Loading...
; + if (error) returnError: {error.message}
; + + return ( +
+ {data.posts.nodes.map(post => (
+
+ );
+}
+```
+
+### Custom Post Types
+
+```graphql
+query GetCustomPostTypeBlocks {
+ books(first: 10) {
+ nodes {
+ id
+ title
+ blocksDataV2 {
+ blocks {
+ id
+ name
+ attributes {
+ name
+ value
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+## Caching Strategies
+
+### Apollo Cache Configuration
+
+```javascript
+const cache = new InMemoryCache({
+ typePolicies: {
+ Query: {
+ fields: {
+ post: {
+ // Cache by ID
+ read(existing, { args, toReference }) {
+ return existing || toReference({
+ __typename: 'Post',
+ id: args.id,
+ });
+ },
+ },
+ },
+ },
+ Post: {
+ fields: {
+ blocksDataV2: {
+ merge(existing, incoming) {
+ return incoming;
+ },
+ },
+ },
+ },
+ },
+});
+```
+
+### Cache-First Strategy
+
+```javascript
+const { data } = useQuery(GET_POST_BLOCKS, {
+ variables: { id: postId },
+ fetchPolicy: 'cache-first', // Use cache if available
+});
+```
+
+### Network-Only Strategy
+
+```javascript
+const { data } = useQuery(GET_POST_BLOCKS, {
+ variables: { id: postId },
+ fetchPolicy: 'network-only', // Always fetch fresh data
+});
+```
+
+### Polling
+
+```javascript
+const { data } = useQuery(GET_POST_BLOCKS, {
+ variables: { id: postId },
+ pollInterval: 30000, // Refetch every 30 seconds
+});
+```
+
+## Next.js Integration
+
+### Static Site Generation
+
+```javascript
+import { ApolloClient, InMemoryCache, gql } from '@apollo/client';
+
+export async function getStaticProps({ params }) {
+ const client = new ApolloClient({
+ uri: 'https://example.com/graphql',
+ cache: new InMemoryCache(),
+ });
+
+ const { data } = await client.query({
+ query: gql`
+ query GetPostBlocks($id: ID!) {
+ post(id: $id, idType: DATABASE_ID) {
+ title
+ blocksDataV2 {
+ blocks {
+ id
+ parentId
+ name
+ attributes {
+ name
+ value
+ isValueJsonEncoded
+ }
+ }
+ }
+ }
+ }
+ `,
+ variables: {
+ id: params.id,
+ },
+ });
+
+ const blocks = transformGraphQLBlocks(data.post.blocksDataV2);
+
+ return {
+ props: {
+ post: data.post,
+ blocks,
+ },
+ revalidate: 60,
+ };
+}
+```
+
+### Server-Side Rendering
+
+```javascript
+export async function getServerSideProps({ params, req }) {
+ const client = new ApolloClient({
+ uri: 'https://example.com/graphql',
+ cache: new InMemoryCache(),
+ headers: {
+ // Forward authentication
+ cookie: req.headers.cookie || '',
+ },
+ });
+
+ const { data } = await client.query({
+ query: GET_POST_BLOCKS,
+ variables: { id: params.id },
+ });
+
+ return {
+ props: {
+ initialApolloState: client.cache.extract(),
+ post: data.post,
+ },
+ };
+}
+```
+
+## Error Handling
+
+### GraphQL Errors
+
+```javascript
+const { loading, error, data } = useQuery(GET_POST_BLOCKS, {
+ variables: { id: postId },
+ onError: (error) => {
+ if (error.networkError) {
+ console.error('Network error:', error.networkError);
+ }
+
+ if (error.graphQLErrors) {
+ error.graphQLErrors.forEach(err => {
+ console.error('GraphQL error:', err.message);
+ console.error('Path:', err.path);
+ console.error('Extensions:', err.extensions);
+ });
+ }
+ },
+});
+```
+
+### Error Boundary
+
+```jsx
+import { ApolloProvider } from '@apollo/client';
+import { ErrorBoundary } from 'react-error-boundary';
+
+function ErrorFallback({ error }) {
+ return (
+
+
+ );
+}
+
+function App() {
+ return (
+ Something went wrong:
+{error.message}
+
+
+ );
+ }
+
+ return (
+ Block not found: {name}
+
+ {blocks.map((block, index) => renderBlock(block, index))}
+
+ );
+};
+```
+
+## Core Block Components
+
+```tsx
+// blocks/CoreParagraph.tsx
+import React from 'react';
+import { BlockComponentProps } from '../types';
+import { BlockRenderer } from '../BlockRenderer';
+
+export const CoreParagraph: React.FC
+
+ {text}
+
+
+ );
+};
+
+// blocks/CoreList.tsx
+export const CoreList: React.FC
+
+ );
+};
+
+// blocks/CoreColumn.tsx
+export const CoreColumn: React.FC
+
+ );
+};
+
+// blocks/CoreGroup.tsx
+export const CoreGroup: React.FC
+
+ );
+};
+
+// blocks/CoreQuote.tsx
+export const CoreQuote: React.FC
+
+ + {value && } ++ ); +}; + +// blocks/index.ts - Export all core blocks +export const coreBlocks = { + 'core/paragraph': CoreParagraph, + 'core/heading': CoreHeading, + 'core/image': CoreImage, + 'core/button': CoreButton, + 'core/buttons': CoreGroup, // Reuse group component + 'core/list': CoreList, + 'core/columns': CoreColumns, + 'core/column': CoreColumn, + 'core/group': CoreGroup, + 'core/quote': CoreQuote, +}; +``` + +## Fetching and Rendering Blocks + +```tsx +// PostContent.tsx +import React, { useEffect, useState } from 'react'; +import { BlockRenderer } from './BlockRenderer'; +import { Block } from './types'; + +interface PostContentProps { + postId: number; +} + +export const PostContent: React.FC+ {citation && ( + + )} +
Loading content...
;
+ }
+
+ if (error) {
+ return Error: {error}
;
+ }
+
+ return (
+
+
+
+ );
+};
+
+// Usage with custom renderers
+{title}
+
+
+ )
+ );
+ }
+
+ return this.props.children;
+ }
+}
+
+// Usage
+Unable to render block
+Loading...
;
+ if (error) return Error: {error.message}
;
+
+ return Loading...
;
+ if (error) return Error: {error}
;
+
+ return
+
+ );
+}
+```
+
+## Error Handling
+
+### Retry Logic
+
+```javascript
+async function fetchWithRetry(url, retries = 3, delay = 1000) {
+ for (let i = 0; i < retries; i++) {
+ try {
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP ${response.status}`);
+ }
+
+ return await response.json();
+ } catch (error) {
+ if (i === retries - 1) throw error;
+
+ console.log(`Retry ${i + 1}/${retries} after ${delay}ms`);
+ await new Promise(resolve => setTimeout(resolve, delay));
+
+ // Exponential backoff
+ delay *= 2;
+ }
+ }
+}
+
+// Usage
+try {
+ const data = await fetchWithRetry(
+ `https://example.com/wp-json/vip-block-data-api/v1/posts/123/blocks`,
+ 3,
+ 1000
+ );
+ console.log('Blocks:', data.blocks);
+} catch (error) {
+ console.error('Failed after retries:', error);
+}
+```
+
+## Next Steps
+
+- [GraphQL Examples](./graphql-examples)
+- [React Renderer](./react-renderer)
+- [REST API Reference](../api/rest-api)
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
new file mode 100644
index 0000000..50bb577
--- /dev/null
+++ b/docs/docs/getting-started.md
@@ -0,0 +1,271 @@
+---
+sidebar_position: 2
+---
+
+# Getting Started
+
+Get up and running with VIP Block Data API in minutes.
+
+## Installation
+
+### WordPress VIP
+
+The plugin is automatically available on WordPress VIP sites. No installation needed!
+
+To activate:
+
+```bash
+# Enable via VIP-CLI
+vip plugin activate vip-block-data-api
+```
+
+Or add to your `vip-config/vip-config.php`:
+
+```php
+wpcom_vip_load_plugin( 'vip-block-data-api' );
+```
+
+### Standard WordPress
+
+#### Via Composer (Recommended)
+
+```bash
+composer require automattic/vip-block-data-api
+```
+
+#### Manual Installation
+
+1. Download the latest release from [GitHub](https://github.com/Automattic/vip-block-data-api/releases)
+2. Upload to `/wp-content/plugins/vip-block-data-api/`
+3. Activate via WordPress admin or WP-CLI:
+
+```bash
+wp plugin activate vip-block-data-api
+```
+
+## Verify Installation
+
+### Test REST API
+
+```bash
+curl https://your-site.com/wp-json/vip-block-data-api/v1/posts/1/blocks
+```
+
+You should receive a JSON response with block data.
+
+### Test GraphQL API (Optional)
+
+First, install [WPGraphQL](https://www.wpgraphql.com/):
+
+```bash
+wp plugin install wp-graphql --activate
+```
+
+Then query your GraphQL endpoint:
+
+```graphql
+query {
+ post(id: "1", idType: DATABASE_ID) {
+ title
+ blocksDataV2 {
+ blocks {
+ name
+ attributes {
+ name
+ value
+ }
+ }
+ }
+ }
+}
+```
+
+## Basic Configuration
+
+### Enable for Custom Post Types
+
+Make sure your custom post types have `show_in_rest` enabled:
+
+```php
+register_post_type( 'book', [
+ 'public' => true,
+ 'show_in_rest' => true, // Required!
+ 'supports' => [ 'editor', 'title' ],
+] );
+```
+
+### Register Custom Blocks
+
+For custom blocks to work properly, register them server-side with `block.json`:
+
+```json
+{
+ "name": "my-plugin/custom-block",
+ "title": "Custom Block",
+ "attributes": {
+ "heading": {
+ "type": "string",
+ "source": "html",
+ "selector": "h2"
+ },
+ "imageUrl": {
+ "type": "string",
+ "source": "attribute",
+ "selector": "img",
+ "attribute": "src"
+ }
+ }
+}
+```
+
+Then register in PHP:
+
+```php
+register_block_type( __DIR__ . '/build/custom-block' );
+```
+
+:::info
+Blocks that are only registered client-side will show warnings and only include delimiter attributes.
+:::
+
+## Your First API Request
+
+### Using cURL
+
+```bash
+# Get all blocks from post ID 123
+curl https://your-site.com/wp-json/vip-block-data-api/v1/posts/123/blocks
+
+# Include only specific block types
+curl "https://your-site.com/wp-json/vip-block-data-api/v1/posts/123/blocks?include=core/paragraph,core/heading"
+
+# Exclude specific block types
+curl "https://your-site.com/wp-json/vip-block-data-api/v1/posts/123/blocks?exclude=core/embed"
+```
+
+### Using JavaScript (Fetch API)
+
+```javascript
+async function getBlocks(postId) {
+ const response = await fetch(
+ `https://your-site.com/wp-json/vip-block-data-api/v1/posts/${postId}/blocks`
+ );
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ return data.blocks;
+}
+
+// Usage
+getBlocks(123)
+ .then(blocks => console.log('Blocks:', blocks))
+ .catch(error => console.error('Error:', error));
+```
+
+### Using WordPress REST API Client
+
+```javascript
+import apiFetch from '@wordpress/api-fetch';
+
+apiFetch({
+ path: '/vip-block-data-api/v1/posts/123/blocks'
+})
+ .then(data => console.log('Blocks:', data.blocks))
+ .catch(error => console.error('Error:', error));
+```
+
+## Next Steps
+
+Now that you have the plugin installed and working:
+
+1. **Explore the APIs** - Learn about [REST API](./api/rest-api) and [GraphQL API](./api/graphql-api)
+2. **Customize behavior** - Check out available [filters](./hooks/filters) and [actions](./hooks/actions)
+3. **Build a renderer** - See the [React renderer example](./examples/react-renderer)
+4. **Filter blocks** - Learn [block filtering techniques](./guides/block-filtering)
+
+## Troubleshooting
+
+### "Post not found" Error
+
+Ensure the post:
+- Exists and is published (or you have permission to view it)
+- Has a post type with `show_in_rest` enabled
+- Is accessible via the WordPress REST API
+
+Test REST API access:
+```bash
+curl https://your-site.com/wp-json/wp/v2/posts/123
+```
+
+### "No blocks found" Warning
+
+This occurs when:
+- Post has no block content (only classic editor content)
+- Post content is empty
+- All blocks are filtered out
+
+### Empty Attributes
+
+If block attributes are missing:
+- Verify the block is registered server-side
+- Check that `block.json` includes attribute sources
+- Ensure the block's HTML matches the selectors
+
+See [Troubleshooting Guide](./advanced/troubleshooting) for more help.
+
+## Configuration Options
+
+### Debug Mode
+
+Enable debug output in responses:
+
+```php
+define( 'VIP_BLOCK_DATA_API__PARSE_DEBUG', true );
+```
+
+This adds raw block data and timing information to API responses.
+
+### Performance Threshold
+
+Set a custom error threshold for slow parsing:
+
+```php
+define( 'WPCOMVIP__BLOCK_DATA_API__PARSE_TIME_ERROR_MS', 1000 ); // 1 second
+```
+
+### Disable GraphQL Integration
+
+```php
+add_filter( 'vip_block_data_api__is_graphql_enabled', '__return_false' );
+```
+
+## Development Setup
+
+For plugin development:
+
+```bash
+# Clone repository
+git clone https://github.com/Automattic/vip-block-data-api.git
+cd vip-block-data-api
+
+# Install dependencies
+composer install
+npm install
+
+# Run tests
+composer run test
+
+# Run linting
+composer run lint
+npm run lint
+```
+
+## Resources
+
+- [REST API Documentation](./api/rest-api)
+- [GraphQL API Documentation](./api/graphql-api)
+- [Code Examples](./examples/rest-api-examples)
+- [WordPress Hooks Reference](./hooks/filters)
diff --git a/docs/docs/guides/block-bindings.md b/docs/docs/guides/block-bindings.md
new file mode 100644
index 0000000..dea261f
--- /dev/null
+++ b/docs/docs/guides/block-bindings.md
@@ -0,0 +1,45 @@
+---
+sidebar_position: 3
+---
+
+# Block Bindings Guide
+
+WordPress 6.5+ introduced block bindings, which allow block attributes to dynamically source values from post meta, custom fields, or other sources.
+
+## What are Block Bindings?
+
+Block bindings connect block attributes to dynamic data sources. The VIP Block Data API automatically resolves these bindings server-side.
+
+## Example
+
+A paragraph block with bound content:
+
+```html
+
+Fallback content
+ +``` + +The API will automatically fetch the value from `custom_description` post meta and include it in the response. + +## Response Format + +```json +{ + "name": "core/paragraph", + "attributes": { + "content": "Value from custom_description meta field" + } +} +``` + +## Requirements + +- WordPress 6.5 or higher +- Block must be registered server-side +- Binding source must be registered + +## Next Steps + +- [WordPress Block Bindings Documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#bindings) +- [Custom Attributes Guide](./custom-attributes) diff --git a/docs/docs/guides/block-filtering.md b/docs/docs/guides/block-filtering.md new file mode 100644 index 0000000..5c533f0 --- /dev/null +++ b/docs/docs/guides/block-filtering.md @@ -0,0 +1,377 @@ +--- +sidebar_position: 1 +--- + +# Block Filtering Guide + +Learn how to filter blocks using query parameters and WordPress hooks. + +## Server-Side Filtering (Recommended) + +Server-side filtering reduces payload size and improves performance by excluding blocks before they're sent to the client. + +### Using Query Parameters + +#### Include Only Specific Blocks + +```bash +# Only paragraphs and headings +GET /wp-json/vip-block-data-api/v1/posts/123/blocks?include=core/paragraph,core/heading +``` + +```javascript +const params = new URLSearchParams({ + include: 'core/paragraph,core/heading,core/image' +}); + +const response = await fetch( + `https://example.com/wp-json/vip-block-data-api/v1/posts/123/blocks?${params}` +); +``` + +#### Exclude Specific Blocks + +```bash +# Exclude all embeds +GET /wp-json/vip-block-data-api/v1/posts/123/blocks?exclude=core/embed,core/html +``` + +```javascript +const excludeBlocks = ['core/embed', 'core/html', 'core-embed/youtube']; + +const params = new URLSearchParams({ + exclude: excludeBlocks.join(',') +}); + +const response = await fetch( + `https://example.com/wp-json/vip-block-data-api/v1/posts/123/blocks?${params}` +); +``` + +:::warning +You cannot use both `include` and `exclude` parameters simultaneously. +::: + +### Using WordPress Filters + +#### Basic Block Filtering + +```php +// Exclude all embed blocks +add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) { + if ( $block_name === 'core/embed' || strpos( $block_name, 'core-embed/' ) === 0 ) { + return false; + } + + return $is_allowed; +}, 10, 3 ); +``` + +#### Conditional Filtering + +```php +// Only allow specific blocks for certain post types +add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) { + $post_id = get_the_ID(); + $post_type = get_post_type( $post_id ); + + // For landing pages, only allow specific blocks + if ( $post_type === 'landing_page' ) { + $allowed_blocks = [ + 'core/heading', + 'core/paragraph', + 'core/image', + 'core/button', + 'core/columns', + 'core/column', + ]; + + return in_array( $block_name, $allowed_blocks, true ); + } + + return $is_allowed; +}, 10, 3 ); +``` + +#### Filtering by Attributes + +```php +// Exclude images without alt text +add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) { + if ( $block_name === 'core/image' ) { + $alt = $block['attrs']['alt'] ?? ''; + + if ( empty( $alt ) ) { + error_log( "Image block without alt text excluded" ); + return false; + } + } + + return $is_allowed; +}, 10, 3 ); +``` + +#### Content-Based Filtering + +```php +// Exclude empty paragraphs +add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) { + if ( $block_name === 'core/paragraph' ) { + $content = $block['innerHTML'] ?? ''; + $clean_content = trim( wp_strip_all_tags( $content ) ); + + if ( empty( $clean_content ) ) { + return false; + } + } + + return $is_allowed; +}, 10, 3 ); +``` + +## Client-Side Filtering + +For dynamic filtering that can't be done server-side: + +### Filter by Block Type + +```javascript +function filterBlocksByType(blocks, allowedTypes) { + return blocks + .filter(block => allowedTypes.includes(block.name)) + .map(block => ({ + ...block, + innerBlocks: block.innerBlocks.length > 0 + ? filterBlocksByType(block.innerBlocks, allowedTypes) + : [] + })); +} + +// Usage +const blocks = await fetchBlocks(123); +const textBlocks = filterBlocksByType(blocks, [ + 'core/paragraph', + 'core/heading', + 'core/list' +]); +``` + +### Exclude Block Types + +```javascript +function excludeBlockTypes(blocks, excludedTypes) { + return blocks + .filter(block => !excludedTypes.includes(block.name)) + .map(block => ({ + ...block, + innerBlocks: block.innerBlocks.length > 0 + ? excludeBlockTypes(block.innerBlocks, excludedTypes) + : [] + })); +} + +// Usage +const blocksWithoutEmbeds = excludeBlockTypes(blocks, [ + 'core/embed', + 'core/html' +]); +``` + +### Advanced Filtering + +```javascript +function filterBlocks(blocks, predicate) { + return blocks + .filter(predicate) + .map(block => ({ + ...block, + innerBlocks: block.innerBlocks.length > 0 + ? filterBlocks(block.innerBlocks, predicate) + : [] + })); +} + +// Filter images with captions +const imagesWithCaptions = filterBlocks(blocks, block => { + if (block.name !== 'core/image') return true; + return block.attributes.caption && block.attributes.caption.length > 0; +}); + +// Filter headings of specific level +const h2Blocks = filterBlocks(blocks, block => { + if (block.name !== 'core/heading') return true; + return block.attributes.level === 2; +}); +``` + +## Common Filtering Patterns + +### Content Security + +```php +// Remove potentially unsafe blocks +add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) { + $unsafe_blocks = [ + 'core/html', + 'core/code', + 'core/shortcode', + ]; + + return ! in_array( $block_name, $unsafe_blocks, true ); +}, 10, 3 ); +``` + +### Mobile Optimization + +```php +// Exclude complex layout blocks for mobile API +add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) { + // Check if request is from mobile + if ( ! wp_is_mobile() ) { + return $is_allowed; + } + + $mobile_excluded = [ + 'core/columns', + 'core/media-text', + 'core/cover', + ]; + + return ! in_array( $block_name, $mobile_excluded, true ); +}, 10, 3 ); +``` + +### Performance Optimization + +```php +// Exclude resource-intensive blocks +add_filter( 'vip_block_data_api__allow_block', function( $is_allowed, $block_name, $block ) { + $heavy_blocks = [ + 'core/gallery', + 'core/video', + 'core/audio', + ]; + + // Only exclude if post has many blocks + $post_content = get_post_field( 'post_content', get_the_ID() ); + $block_count = substr_count( $post_content, '.*?/s', + '', + $post_content + ); + + return $post_content; +}, 10, 2 ); +``` + +**Example: Replace Shortcodes** + +```php +add_filter( 'vip_block_data_api__before_parse_post_content', function( $post_content, $post_id ) { + // Replace legacy shortcodes with blocks + $post_content = str_replace( + '[gallery]', + '', + $post_content + ); + + return $post_content; +}, 10, 2 ); +``` + +--- + +### `vip_block_data_api__after_parse_blocks` + +Modify the final API response after all blocks have been parsed. + +**Parameters:** +- `$result` *(array)* - The complete API response with blocks +- `$post_id` *(int)* - The post ID + +**Returns:** *(array)* - The modified response + +**Example: Add Post Metadata** + +```php +add_filter( 'vip_block_data_api__after_parse_blocks', function( $result, $post_id ) { + $post = get_post( $post_id ); + + // Add post metadata to response + $result['postMeta'] = [ + 'author' => get_the_author_meta( 'display_name', $post->post_author ), + 'date' => get_the_date( 'c', $post ), + 'modified' => get_the_modified_date( 'c', $post ), + 'categories' => wp_get_post_categories( $post_id, [ 'fields' => 'names' ] ), + 'tags' => wp_get_post_tags( $post_id, [ 'fields' => 'names' ] ), + ]; + + return $result; +}, 10, 2 ); +``` + +**Example: Add Block Statistics** + +```php +add_filter( 'vip_block_data_api__after_parse_blocks', function( $result, $post_id ) { + $blocks = $result['blocks'] ?? []; + + // Count blocks by type + $block_counts = []; + $total_word_count = 0; + + array_walk_recursive( $blocks, function( $value, $key ) use ( &$block_counts, &$total_word_count ) { + if ( $key === 'name' ) { + $block_counts[ $value ] = ( $block_counts[ $value ] ?? 0 ) + 1; + } + if ( $key === 'content' && is_string( $value ) ) { + $total_word_count += str_word_count( wp_strip_all_tags( $value ) ); + } + } ); + + $result['statistics'] = [ + 'totalBlocks' => count( $blocks ), + 'blockCounts' => $block_counts, + 'totalWordCount' => $total_word_count, + 'estimatedReadTime' => ceil( $total_word_count / 200 ), // Assuming 200 words per minute + ]; + + return $result; +}, 10, 2 ); +``` + +**Example: Add Debug Information** + +```php +add_filter( 'vip_block_data_api__after_parse_blocks', function( $result, $post_id ) { + if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) { + $result['debug'] = [ + 'timestamp' => current_time( 'c' ), + 'memory_usage' => memory_get_usage( true ), + 'query_count' => get_num_queries(), + ]; + } + + return $result; +}, 10, 2 ); +``` + +--- + +## GraphQL Integration + +### `vip_block_data_api__is_graphql_enabled` + +Enable or disable GraphQL integration. + +**Parameters:** +- `$is_graphql_enabled` *(bool)* - Whether GraphQL is enabled (default: true if WPGraphQL is active) + +**Returns:** *(bool)* - Whether to enable GraphQL integration + +**Example: Disable GraphQL** + +```php +add_filter( 'vip_block_data_api__is_graphql_enabled', '__return_false' ); +``` + +**Example: Conditional GraphQL** + +```php +add_filter( 'vip_block_data_api__is_graphql_enabled', function( $is_enabled ) { + // Only enable GraphQL for administrators + return current_user_can( 'manage_options' ); +} ); +``` + +--- + +## Filter Priority Best Practices + +When using multiple filters, priority matters: + +```php +// Run first (priority 5) +add_filter( 'vip_block_data_api__allow_block', 'exclude_embeds', 5, 3 ); + +// Run second (priority 10, default) +add_filter( 'vip_block_data_api__allow_block', 'exclude_html', 10, 3 ); + +// Run last (priority 20) +add_filter( 'vip_block_data_api__allow_block', 'log_excluded_blocks', 20, 3 ); +``` + +## Performance Considerations + +- **Cache expensive operations** - Use transients or object cache +- **Limit database queries** - Batch queries when possible +- **Avoid heavy processing** - Defer to client-side when appropriate +- **Test with large posts** - Ensure filters don't slow down parsing + +## Next Steps + +- [Actions Reference](./actions) +- [Block Filtering Guide](../guides/block-filtering) +- [Custom Attributes Guide](../guides/custom-attributes) +- [Filtering Examples](../examples/filtering-blocks) diff --git a/docs/docs/intro.md b/docs/docs/intro.md new file mode 100644 index 0000000..1a5196f --- /dev/null +++ b/docs/docs/intro.md @@ -0,0 +1,91 @@ +--- +sidebar_position: 1 +slug: / +--- + +# Introduction + +**VIP Block Data API** is a WordPress plugin that converts Gutenberg block editor content into structured JSON data. It's designed for headless WordPress applications, enabling developers to consume block content through standardized REST and GraphQL APIs instead of parsing HTML. + +## Key Features + +- 🚀 **REST API** - Simple REST endpoint for fetching block data as nested JSON +- 📊 **GraphQL API** - Seamless integration with WPGraphQL +- 🎯 **Block Filtering** - Include/exclude specific block types +- 🔌 **Extensible** - Comprehensive hooks and filters for customization +- ⚡ **Performance** - Built-in caching and optimizations for VIP sites +- 🔒 **Secure** - Respects WordPress permissions and access controls +- 🎨 **Block Bindings** - Full support for WordPress 6.5+ block bindings +- 🔄 **Synced Patterns** - Automatically expands reusable blocks + +## Why Use This Plugin? + +Traditional WordPress themes render blocks as HTML, which is difficult to parse and manipulate in decoupled applications. This plugin: + +1. **Provides structured data** - Get clean JSON instead of HTML soup +2. **Preserves block hierarchy** - Maintains parent-child relationships +3. **Extracts attributes correctly** - Uses server-side block registration for accurate parsing +4. **Handles complex blocks** - Supports all WordPress attribute sources +5. **Enables headless WordPress** - Perfect for React, Vue, or mobile apps + +## Use Cases + +- **Headless WordPress sites** - Build frontends with React, Next.js, Vue, etc. +- **Mobile applications** - Native iOS/Android apps consuming WordPress content +- **Content as a Service** - Expose WordPress as a content API +- **Multi-platform publishing** - One content source, many destinations +- **Custom block renderers** - Build your own block rendering logic + +## Quick Example + +### REST API Request +```bash +GET /wp-json/vip-block-data-api/v1/posts/123/blocks +``` + +### Response +```json +{ + "blocks": [ + { + "name": "core/heading", + "attributes": { + "level": 2, + "content": "Welcome to My Site" + }, + "innerBlocks": [] + }, + { + "name": "core/paragraph", + "attributes": { + "content": "This is a paragraph with bold text." + }, + "innerBlocks": [] + } + ] +} +``` + +## Requirements + +- **WordPress:** 6.0 or higher +- **PHP:** 8.1 or higher +- **WPGraphQL:** Optional, required only for GraphQL functionality + +## What's Next? + +- [Get Started](./getting-started) - Installation and basic setup +- [REST API Reference](./api/rest-api) - Complete REST API documentation +- [GraphQL API Reference](./api/graphql-api) - Complete GraphQL documentation +- [WordPress Hooks](./hooks/filters) - Customize with filters and actions +- [Examples](./examples/rest-api-examples) - Real-world code examples + +## Support + +- 🐛 [Report Issues](https://github.com/Automattic/vip-block-data-api/issues) +- 📖 [View Source Code](https://github.com/Automattic/vip-block-data-api) +- 💬 [WordPress VIP Support](https://wpvip.com/support/) + +## License + +This plugin is licensed under [GPL-3.0](https://github.com/Automattic/vip-block-data-api/blob/trunk/LICENSE). diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js new file mode 100644 index 0000000..a4b46d2 --- /dev/null +++ b/docs/docusaurus.config.js @@ -0,0 +1,137 @@ +// @ts-check +// Note: type annotations allow type checking and IDEs autocompletion + +const {themes} = require('prism-react-renderer'); +const lightCodeTheme = themes.github; +const darkCodeTheme = themes.dracula; + +/** @type {import('@docusaurus/types').Config} */ +const config = { + title: 'VIP Block Data API', + tagline: 'Convert Gutenberg blocks into structured JSON for headless WordPress', + favicon: 'img/favicon.ico', + + // Set the production url of your site here + url: 'https://automattic.github.io', + // Set the /