Skip to content

Commit ca58fdf

Browse files
whyisjakeclaude
whyisjake
and
claude
committed
Add comprehensive GitHub Pages documentation site
This commit adds a complete Docusaurus-based documentation site for the VIP Block Data API plugin with the following features: ## Documentation Structure - Introduction and getting started guide - Complete REST API reference with code examples - Full GraphQL API documentation - WordPress hooks reference (filters and actions) - How-to guides for common use cases - Advanced topics (performance, caching, troubleshooting) - Extensive code examples for React, Next.js, and more ## Technical Implementation - Built with Docusaurus 3.x (React-based) - WordPress VIP design system and color scheme - Responsive layout with dark mode support - Comprehensive code examples in PHP, JavaScript, TypeScript, GraphQL - TypeScript type definitions for block structures - Complete React block renderer implementation ## Key Features - Automatic GitHub Pages deployment via GitHub Actions - Search-ready (Algolia DocSearch integration) - Mobile-responsive design - Extensive real-world examples - Best practices for WordPress and React ## Documentation Coverage - REST API endpoints and parameters - GraphQL queries with Apollo Client - All WordPress filters and actions - Block filtering techniques - Custom attribute examples - Performance optimization strategies - Caching implementations - Common troubleshooting scenarios 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent b992ce2 commit ca58fdf

29 files changed

+24588
-0
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Deploy Documentation to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- trunk
7+
paths:
8+
- 'docs/**'
9+
- '.github/workflows/deploy-docs.yml'
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: "pages"
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
name: Build Documentation
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
29+
- name: Setup Node.js
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: 18
33+
cache: npm
34+
cache-dependency-path: docs/package-lock.json
35+
36+
- name: Setup Pages
37+
uses: actions/configure-pages@v4
38+
39+
- name: Install dependencies
40+
working-directory: ./docs
41+
run: npm ci
42+
43+
- name: Build website
44+
working-directory: ./docs
45+
run: npm run build
46+
47+
- name: Upload artifact
48+
uses: actions/upload-pages-artifact@v3
49+
with:
50+
path: ./docs/build
51+
52+
deploy:
53+
name: Deploy to GitHub Pages
54+
environment:
55+
name: github-pages
56+
url: ${{ steps.deployment.outputs.page_url }}
57+
runs-on: ubuntu-latest
58+
needs: build
59+
steps:
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v4

‎docs/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# VIP Block Data API Documentation
2+
3+
This directory contains the documentation website for the VIP Block Data API plugin, built with [Docusaurus](https://docusaurus.io/).
4+
5+
## Development
6+
7+
### Prerequisites
8+
9+
- Node.js 18.0 or higher
10+
- npm or yarn
11+
12+
### Installation
13+
14+
```bash
15+
npm install
16+
```
17+
18+
### Local Development
19+
20+
Start the development server:
21+
22+
```bash
23+
npm start
24+
```
25+
26+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
27+
28+
### Build
29+
30+
Generate static content for production:
31+
32+
```bash
33+
npm run build
34+
```
35+
36+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
37+
38+
### Serve Built Site
39+
40+
Test the production build locally:
41+
42+
```bash
43+
npm run serve
44+
```
45+
46+
### Deployment
47+
48+
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`).
49+
50+
## Documentation Structure
51+
52+
```
53+
docs/
54+
├── docs/ # Documentation pages
55+
│ ├── intro.md # Introduction and overview
56+
│ ├── getting-started.md # Installation and setup guide
57+
│ ├── api/ # API reference documentation
58+
│ │ ├── rest-api.md # REST API reference
59+
│ │ ├── graphql-api.md # GraphQL API reference
60+
│ │ └── response-format.md # Response format details
61+
│ ├── hooks/ # WordPress hooks documentation
62+
│ │ ├── filters.md # Filters reference
63+
│ │ └── actions.md # Actions reference
64+
│ ├── guides/ # How-to guides
65+
│ │ ├── block-filtering.md
66+
│ │ ├── custom-attributes.md
67+
│ │ ├── block-bindings.md
68+
│ │ └── synced-patterns.md
69+
│ ├── examples/ # Code examples
70+
│ │ ├── rest-api-examples.md
71+
│ │ ├── graphql-examples.md
72+
│ │ ├── react-renderer.md
73+
│ │ └── filtering-blocks.md
74+
│ └── advanced/ # Advanced topics
75+
│ ├── block-attribute-sources.md
76+
│ ├── performance.md
77+
│ ├── caching.md
78+
│ └── troubleshooting.md
79+
├── src/ # Custom components and styles
80+
│ └── css/
81+
│ └── custom.css # Custom CSS
82+
├── static/ # Static files
83+
│ └── img/ # Images
84+
├── docusaurus.config.js # Docusaurus configuration
85+
├── sidebars.js # Sidebar navigation
86+
└── package.json # Dependencies
87+
88+
## Writing Documentation
89+
90+
### Creating a New Page
91+
92+
1. Create a new Markdown file in the appropriate directory under `docs/`
93+
2. Add frontmatter at the top of the file:
94+
95+
```markdown
96+
---
97+
sidebar_position: 1
98+
title: Page Title
99+
---
100+
101+
# Page Title
102+
103+
Your content here...
104+
```
105+
106+
3. The page will automatically be added to the documentation site
107+
108+
### Code Blocks
109+
110+
Use fenced code blocks with language identifiers:
111+
112+
```markdown
113+
```javascript
114+
function example() {
115+
return 'Hello World';
116+
}
117+
\```
118+
```
119+
120+
Supported languages include: `javascript`, `typescript`, `php`, `bash`, `json`, `graphql`, `jsx`, `tsx`, and more.
121+
122+
### Callouts
123+
124+
Use callouts for important information:
125+
126+
```markdown
127+
:::info
128+
This is informational content.
129+
:::
130+
131+
:::warning
132+
This is a warning.
133+
:::
134+
135+
:::danger
136+
This is dangerous!
137+
:::
138+
139+
:::tip
140+
This is a helpful tip.
141+
:::
142+
```
143+
144+
### Links
145+
146+
Internal links (to other docs pages):
147+
148+
```markdown
149+
[Link text](./other-page.md)
150+
[Link text](../category/page.md)
151+
```
152+
153+
External links:
154+
155+
```markdown
156+
[WordPress VIP](https://wpvip.com/)
157+
```
158+
159+
## Styling
160+
161+
Custom styles are defined in `src/css/custom.css`. The documentation follows the WordPress VIP design system.
162+
163+
### Color Variables
164+
165+
```css
166+
--ifm-color-primary: #0675C4;
167+
--ifm-color-primary-dark: #0569b1;
168+
/* See custom.css for complete list */
169+
```
170+
171+
## Contributing
172+
173+
When contributing to the documentation:
174+
175+
1. Ensure your changes follow the existing style and structure
176+
2. Test locally with `npm start` before committing
177+
3. Check that the build succeeds with `npm run build`
178+
4. Keep examples practical and well-commented
179+
5. Update the sidebar configuration in `sidebars.js` if adding new sections
180+
181+
## Resources
182+
183+
- [Docusaurus Documentation](https://docusaurus.io/docs)
184+
- [Markdown Guide](https://www.markdownguide.org/)
185+
- [WordPress VIP](https://wpvip.com/)
186+
- [Plugin Repository](https://github.com/Automattic/vip-block-data-api)
187+
188+
## License
189+
190+
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‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Block Attribute Sources
6+
7+
Understanding how the VIP Block Data API extracts block attributes from HTML.
8+
9+
## Attribute Source Types
10+
11+
The plugin supports all WordPress attribute sources:
12+
13+
### 1. `attribute`
14+
15+
Extracts HTML element attributes:
16+
17+
```json
18+
{
19+
"url": {
20+
"type": "string",
21+
"source": "attribute",
22+
"selector": "img",
23+
"attribute": "src"
24+
}
25+
}
26+
```
27+
28+
### 2. `html`
29+
30+
Extracts inner HTML content:
31+
32+
```json
33+
{
34+
"content": {
35+
"type": "string",
36+
"source": "html",
37+
"selector": "p"
38+
}
39+
}
40+
```
41+
42+
### 3. `text`
43+
44+
Extracts plain text content:
45+
46+
```json
47+
{
48+
"citation": {
49+
"type": "string",
50+
"source": "text",
51+
"selector": "cite"
52+
}
53+
}
54+
```
55+
56+
### 4. `query`
57+
58+
Extracts arrays of data:
59+
60+
```json
61+
{
62+
"images": {
63+
"type": "array",
64+
"source": "query",
65+
"selector": "img",
66+
"query": {
67+
"url": {
68+
"type": "string",
69+
"source": "attribute",
70+
"attribute": "src"
71+
},
72+
"alt": {
73+
"type": "string",
74+
"source": "attribute",
75+
"attribute": "alt"
76+
}
77+
}
78+
}
79+
}
80+
```
81+
82+
## Server-Side Registration Required
83+
84+
For custom blocks, server-side registration with `block.json` is required:
85+
86+
```php
87+
register_block_type( __DIR__ . '/build/custom-block' );
88+
```
89+
90+
## Next Steps
91+
92+
- [WordPress Block API](https://developer.wordpress.org/block-editor/reference-guides/block-api/)
93+
- [Getting Started Guide](../getting-started)

0 commit comments

Comments
 (0)