Documentation pass numero 2 (#36)

* initial pass

* mild tweaks

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+## Guidelines
+
+- As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](https://make.wordpress.org/handbook/community-code-of-conduct/).
+
+- Contributors should review WordPress' [PHP coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/), WordPress' [JavaScript coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/) and [accessibility coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/).
+
+- Accessibility should be top of mind and thoroughly tested.
+
+- You maintain copyright over any contribution you make. By submitting a pull request you agree to release that code under [Remote Data Blocks' License](LICENSE.md).
+
+- When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
+
+## Development Setup
+
+For WP monolith:
+
+```
+npm install && npm run start:monolith
+```
+
+For WP backend + WP Components w/Next.js frontend, make sure the [wp-components repo](https://github.com/Automattic/wp-components) is at a peer level in your file system and then run from root here:
+
+```
+npm install && npm run start:decoupled
+```
+
+## Reporting Security Issues
+
+Please see [SECURITY.md](SECURITY.md).

README.md

@@ -4,7 +4,7 @@ Remote Data Blocks is a WordPress plugin that brings an assortment of flexible,
 
 ## Setup
 
-1. Download the Remote Data Blocks plugin zip file.
+1. Download the [Remote Data Blocks plugin zip file](https://github.com/Automattic/remote-data-blocks/releases/latest/download/remote-data-blocks.zip).
 2. Log in to your WordPress admin panel.
 3. Navigate to Plugins > Add New.
 4. Click the "Upload Plugin" button at the top of the page.
@@ -17,11 +17,11 @@ Remote Data Blocks is a WordPress plugin that brings an assortment of flexible,
 2. Search for "remote" in the block inserter.
 3. Choose from the available blocks, such as:
 
-   - Airtable Event
-   - Elden Ring Map
+   - Airtable Events
    - Art Institute of Chicago
-   - Zip Code
-   - Shopify Product
+   - GitHub Files
+   - Zip Code Information
+   - Shopify Products
 
 4. Configure the block settings in the sidebar:
 
@@ -35,18 +35,4 @@ Remote Data Blocks is a WordPress plugin that brings an assortment of flexible,
 
 6. Use the blocks to display dynamic content from various sources directly in your posts or pages.
 
-7. Developers: extend the plugin by creating new datasources and queries. See the example files in the `example` directory for reference.
-
-## Contributing
-
-For WP monolith:
-
-```
-npm install && npm run start:monolith
-```
-
-For WP backend + WP Components w/Next.js frontend dev environment, make sure the [wp-components repo](https://github.com/Automattic/wp-components) is at peer level on your file system and then run from root here:
-
-```
-npm install && npm run start:decoupled
-```
+Developers! You can [extend](docs/extending.md) the plugin by creating new datasources and queries.

SECURITY.md

@@ -0,0 +1,5 @@
+# Reporting Security Issues
+
+WPVIP and Automattic take security bugs seriously. We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.
+
+To report a security issue, please visit [Automattic's HackerOne](https://hackerone.com/automattic) program.

docs/concepts.md

@@ -0,0 +1,28 @@
+# Remote Data Blocks: Core Concepts
+
+Remote Data Blocks is a WordPress plugin that enhances the Gutenberg editor by providing flexible, data-enrichable blocks. These blocks allow authors to seamlessly integrate local WordPress data, remote data, and custom layouts within the block editor.
+
+### Block-Based Architecture
+
+The plugin leverages WordPress's block editor (Gutenberg) to create custom blocks that can fetch and display data from various sources. Each block is designed to be modular and reusable.
+
+### Remote Data Integration
+
+Remote data is bound to blocks and, later, rendered via WordPress' Block Binding API.
+This enables dynamic content display directly within posts or pages using external data sources, such as:
+
+- Airtable
+- Elden Ring Map API
+- Art Institute of Chicago API
+- Zip Code databases
+- Shopify
+
+### Flexible Configuration
+
+Each block comes with its own set of configurable options, allowing users to customize the data retrieval and display according to their needs.
+
+### Developer Extensibility
+
+The plugin is designed to be extendable, allowing developers to create new datasources and queries to expand its functionality.
+
+See the [extending](extending.md) documentation for more information.

docs/data-flow.md

@@ -0,0 +1,34 @@
+# Remote Data Blocks: Data Flow
+
+## Overview
+
+This document outlines the data flow within the Remote Data Blocks WordPress plugin, explaining how data moves from external sources to the Gutenberg editor and finally to the frontend display.
+
+## Data Flow Steps
+
+1. **Block Insertion**:
+
+   - User adds a Remote Data Block to their post/page.
+   - The block is initialized with default settings.
+
+2. **Block Configuration**:
+
+   - User configures the block settings in the sidebar.
+   - For data-driven blocks, users can search or select specific items.
+
+3. **Data Fetching**:
+
+   - The block sends a request to the appropriate API or data source.
+   - Data is retrieved based on the block's configuration.
+
+4. **Data Processing**:
+
+   - Retrieved data is processed and formatted according to the block's requirements.
+
+5. **Rendering**:
+
+   - The block renders the processed data within the editor.
+   - On the frontend, the block displays the data to site visitors.
+
+6. **Updates and Real-time Changes**:
+   - Some blocks may support real-time updates or periodic data refreshes.

docs/extending.md

@@ -0,0 +1,94 @@
+# Remote Data Blocks: Extending the Plugin
+
+Remote Data Blocks is designed to be extensible, allowing developers to create new data sources and queries. This guide will walk you through the process of extending the core plugin.
+
+## 1. Creating a New Data Source
+
+To create a new data source:
+
+1. Create a new PHP class that extends the `HttpDatasource` class.
+2. Implement the required methods for fetching and processing data.
+
+Example:
+
+```php
+class YourCustomDatasource extends HttpDatasource {
+	public function get_endpoint(): string {
+        // Implement your endpoint logic here
+	}
+
+	public function get_request_headers(): array {
+        // Implement your headers logic here
+	}
+}
+```
+
+## 2. Creating a New Query
+
+To create a new query:
+
+1. Create a new PHP class that extends the `QueryContext` class.
+2. Implement the required input and output variables for executing the query.
+3. Optionally implement overrides of base class methods if needed.
+
+Example:
+
+```php
+class YourCustomQuery extends QueryContext {
+    public array $input_variables = [
+        // Implement your input variables here
+    ];
+
+    public array $output_variables = [
+        // Implement your output variables here
+    ];
+
+    public function get_endpoint( array $input_variables ): string {
+        // Optionally implemented override of datasource endpoint logic here
+        // eg, to add additional query parameters
+    }
+}
+```
+
+## 3. Registering Your New Block
+
+To register your new block:
+
+1. Create a new PHP file for registering your block.
+2. Use the `ConfigurationLoader` class to register your block, queries, and patterns.
+
+Example:
+
+```php
+use RemoteDataBlocks\Editor\ConfigurationLoader;
+
+function register_your_custom_block() {
+    $block_name = 'Your Custom Block';
+    $your_datasource = new YourCustomDatasource();
+    $your_query = new YourCustomQuery( $your_datasource );
+    ConfigurationLoader::register_block( $block_name, $your_query );
+    ConfigurationLoader::register_list_query( $block_name, $your_query );
+    $block_pattern = file_get_contents( __DIR__ . '/your-pattern.html' );
+    ConfigurationLoader::register_block_pattern( $block_name, 'your-namespace/your-pattern', $block_pattern );
+}
+add_action( 'register_remote_data_blocks', 'YourNamespace\\register_your_custom_block' );
+```
+
+## 4. Creating Block Patterns
+
+Create HTML patterns for your block to define how the data should be displayed. Use the Remote Data Blocks binding syntax to connect data to your pattern.
+
+Example:
+
+```html
+<!-- wp:group {"layout":{"type":"constrained"}} -->
+<div class="wp-block-group">
+	<!-- wp:heading {"metadata":{"bindings":{"content":{"source":"remote-data/binding","args":{"field":"title"}}}}} -->
+	<h2 class="wp-block-heading"></h2>
+	<!-- /wp:heading -->
+	<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"remote-data/binding","args":{"field":"description"}}}}} -->
+	<p></p>
+	<!-- /wp:paragraph -->
+</div>
+<!-- /wp:group -->
+```