Add comprehensive GitHub Pages documentation site

.github/workflows/deploy-docs.yml

@@ -0,0 +1,62 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - trunk
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        working-directory: ./docs
+        run: npm ci
+
+      - name: Build website
+        working-directory: ./docs
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,190 @@
+# VIP Block Data API Documentation
+
+This directory contains the documentation website for the VIP Block Data API plugin, built with [Docusaurus](https://docusaurus.io/).
+
+## Development
+
+### Prerequisites
+
+- Node.js 18.0 or higher
+- npm or yarn
+
+### Installation
+
+```bash
+npm install
+```
+
+### Local Development
+
+Start the development server:
+
+```bash
+npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+Generate static content for production:
+
+```bash
+npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Serve Built Site
+
+Test the production build locally:
+
+```bash
+npm run serve
+```
+
+### Deployment
+
+The documentation is automatically deployed to GitHub Pages when changes are pushed to the `trunk` branch. The deployment is handled by GitHub Actions (see `.github/workflows/deploy-docs.yml`).
+
+## Documentation Structure
+
+```
+docs/
+├── docs/                    # Documentation pages
+│   ├── intro.md            # Introduction and overview
+│   ├── getting-started.md  # Installation and setup guide
+│   ├── api/                # API reference documentation
+│   │   ├── rest-api.md     # REST API reference
+│   │   ├── graphql-api.md  # GraphQL API reference
+│   │   └── response-format.md # Response format details
+│   ├── hooks/              # WordPress hooks documentation
+│   │   ├── filters.md      # Filters reference
+│   │   └── actions.md      # Actions reference
+│   ├── guides/             # How-to guides
+│   │   ├── block-filtering.md
+│   │   ├── custom-attributes.md
+│   │   ├── block-bindings.md
+│   │   └── synced-patterns.md
+│   ├── examples/           # Code examples
+│   │   ├── rest-api-examples.md
+│   │   ├── graphql-examples.md
+│   │   ├── react-renderer.md
+│   │   └── filtering-blocks.md
+│   └── advanced/           # Advanced topics
+│       ├── block-attribute-sources.md
+│       ├── performance.md
+│       ├── caching.md
+│       └── troubleshooting.md
+├── src/                    # Custom components and styles
+│   └── css/
+│       └── custom.css      # Custom CSS
+├── static/                 # Static files
+│   └── img/               # Images
+├── docusaurus.config.js    # Docusaurus configuration
+├── sidebars.js            # Sidebar navigation
+└── package.json           # Dependencies
+
+## Writing Documentation
+
+### Creating a New Page
+
+1. Create a new Markdown file in the appropriate directory under `docs/`
+2. Add frontmatter at the top of the file:
+
+```markdown
+---
+sidebar_position: 1
+title: Page Title
+---
+
+# Page Title
+
+Your content here...
+```
+
+3. The page will automatically be added to the documentation site
+
+### Code Blocks
+
+Use fenced code blocks with language identifiers:
+
+```markdown
+```javascript
+function example() {
+  return 'Hello World';
+}
+\```
+```
+
+Supported languages include: `javascript`, `typescript`, `php`, `bash`, `json`, `graphql`, `jsx`, `tsx`, and more.
+
+### Callouts
+
+Use callouts for important information:
+
+```markdown
+:::info
+This is informational content.
+:::
+
+:::warning
+This is a warning.
+:::
+
+:::danger
+This is dangerous!
+:::
+
+:::tip
+This is a helpful tip.
+:::
+```
+
+### Links
+
+Internal links (to other docs pages):
+
+```markdown
+[Link text](./other-page.md)
+[Link text](../category/page.md)
+```
+
+External links:
+
+```markdown
+[WordPress VIP](https://wpvip.com/)
+```
+
+## Styling
+
+Custom styles are defined in `src/css/custom.css`. The documentation follows the WordPress VIP design system.
+
+### Color Variables
+
+```css
+--ifm-color-primary: #0675C4;
+--ifm-color-primary-dark: #0569b1;
+/* See custom.css for complete list */
+```
+
+## Contributing
+
+When contributing to the documentation:
+
+1. Ensure your changes follow the existing style and structure
+2. Test locally with `npm start` before committing
+3. Check that the build succeeds with `npm run build`
+4. Keep examples practical and well-commented
+5. Update the sidebar configuration in `sidebars.js` if adding new sections
+
+## Resources
+
+- [Docusaurus Documentation](https://docusaurus.io/docs)
+- [Markdown Guide](https://www.markdownguide.org/)
+- [WordPress VIP](https://wpvip.com/)
+- [Plugin Repository](https://github.com/Automattic/vip-block-data-api)
+
+## License
+
+The documentation is part of the VIP Block Data API plugin and is licensed under GPL-3.0.

docs/docs/advanced/block-attribute-sources.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 1
+---
+
+# Block Attribute Sources
+
+Understanding how the VIP Block Data API extracts block attributes from HTML.
+
+## Attribute Source Types
+
+The plugin supports all WordPress attribute sources:
+
+### 1. `attribute`
+
+Extracts HTML element attributes:
+
+```json
+{
+  "url": {
+    "type": "string",
+    "source": "attribute",
+    "selector": "img",
+    "attribute": "src"
+  }
+}
+```
+
+### 2. `html`
+
+Extracts inner HTML content:
+
+```json
+{
+  "content": {
+    "type": "string",
+    "source": "html",
+    "selector": "p"
+  }
+}
+```
+
+### 3. `text`
+
+Extracts plain text content:
+
+```json
+{
+  "citation": {
+    "type": "string",
+    "source": "text",
+    "selector": "cite"
+  }
+}
+```
+
+### 4. `query`
+
+Extracts arrays of data:
+
+```json
+{
+  "images": {
+    "type": "array",
+    "source": "query",
+    "selector": "img",
+    "query": {
+      "url": {
+        "type": "string",
+        "source": "attribute",
+        "attribute": "src"
+      },
+      "alt": {
+        "type": "string",
+        "source": "attribute",
+        "attribute": "alt"
+      }
+    }
+  }
+}
+```
+
+## Server-Side Registration Required
+
+For custom blocks, server-side registration with `block.json` is required:
+
+```php
+register_block_type( __DIR__ . '/build/custom-block' );
+```
+
+## Next Steps
+
+- [WordPress Block API](https://developer.wordpress.org/block-editor/reference-guides/block-api/)
+- [Getting Started Guide](../getting-started)