add documentation

.github/workflows/deploy-docs.yml

@@ -0,0 +1,56 @@
+name: Deploy Docusaurus site to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # paths:
+    #   - 'docs/**'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+      - name: Build website
+        run: npm run build
+        working-directory: docs
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

SECURITY.md

@@ -4,7 +4,7 @@
 
 If you discover a security vulnerability in AssertJ JSON, please **do not** create a public GitHub issue. Instead, please report it responsibly by:
 
-1. **Email**: Send a detailed report to [security@example.com] with:
+1. **Email**: Send a detailed report to [assertj-json@archyoshi.com] with:
    - Description of the vulnerability
    - Steps to reproduce (if applicable)
    - Potential impact

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,43 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+npm install
+```
+
+**Note**: feel free to use the package manager of your choice.
+
+## Local Development
+
+```bash
+npm run 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
+
+```bash
+npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true npm run deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> npm run deploy
+```
+
+If you are using GitHub Pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/code-and-issue-tracker.md

@@ -0,0 +1,22 @@
+---
+title: Code and Issue Tracker
+sidebar_position: 7
+---
+
+# Code and Issue Tracker
+
+AssertJ-JSON is open source. The source code and issue tracker are hosted on GitHub.
+
+## Source Code
+
+You can browse the source code, fork the project, and submit pull requests on GitHub:
+
+*   **Repository:** [github.com/archyoshi/assertj-json](https://github.com/archyoshi/assertj-json)
+
+## Issue Tracker
+
+If you find a bug or have a feature request, please report it in the GitHub issue tracker:
+
+*   **Issues:** [github.com/archyoshi/assertj-json/issues](https://github.com/archyoshi/assertj-json/issues)
+
+When reporting a bug, please provide a minimal, reproducible example and details about the version you are using.

docs/docs/concepts.md

@@ -0,0 +1,31 @@
+---
+title: Concepts
+sidebar_position: 2
+---
+
+# Concepts
+
+AssertJ-JSON is built on top of AssertJ and Jackson to provide a fluent and intuitive way to test JSON payloads.
+
+## Extension of AssertJ
+
+AssertJ-JSON follows the same principles as [AssertJ Core](https://assertj.github.io/doc/). It provides a fluent API where you chain assertions on your JSON objects. This means that if you are familiar with AssertJ, you will feel right at home using AssertJ-JSON.
+
+Instead of writing complex code to parse JSON and then asserting on the parsed objects, AssertJ-JSON handles the parsing under the hood and gives you direct methods like `hasField` and `hasValueForField`.
+
+## Jackson Integration
+
+Under the hood, AssertJ-JSON leverages [Jackson](https://github.com/FasterXML/jackson), a high-performance JSON processor for Java. It automatically converts your JSON inputs into Jackson's `JsonNode` or `ObjectNode` trees.
+
+You can also pass a custom `ObjectMapper` if your JSON requires specific configuration (such as custom deserializers, date formats, or ignoring unknown properties) during the parsing phase.
+
+## Versatile Inputs
+
+AssertJ-JSON is designed to be flexible with the type of input it receives. You can assert directly on:
+
+1.  **JSON Strings:** Perfect for small payloads or inline JSON strings in your tests.
+2.  **`JsonNode` / `ObjectNode`:** If you have already parsed the JSON in your test, you can pass the node directly.
+3.  **`java.nio.file.Path`:** Read JSON directly from a file path.
+4.  **`java.io.File`:** Standard Java `File` objects are also fully supported.
+
+This makes it easy to maintain external JSON fixture files and assert that your API responses match the expected contents exactly, without manual File I/O in every test.

docs/docs/contributing.md

@@ -0,0 +1,31 @@
+---
+title: Contributing
+sidebar_position: 8
+---
+
+# Contributing
+
+We welcome contributions to AssertJ-JSON! Whether it is a bug report, feature request, or a pull request, your input is highly valued.
+
+## Building the Project
+
+If you want to contribute code, you can easily build the project locally using the provided Maven wrapper.
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/archyoshi/assertj-json.git
+   cd assertj-json
+   ```
+
+2. **Build and test:**
+   ```bash
+   ./mvnw clean verify
+   ```
+   This will compile the code and run all the tests. Ensure that all tests pass before submitting a pull request.
+
+## Pull Request Process
+
+1. Fork the repository and create your branch from `main`.
+2. Add tests for any new features or bug fixes.
+3. Ensure the code builds and all tests pass via `./mvnw clean verify`.
+4. Submit your pull request with a clear description of the changes.

docs/docs/examples.md

@@ -0,0 +1,111 @@
+---
+title: Examples
+sidebar_position: 5
+---
+
+# Examples
+
+Here are some complete, copy-pasteable examples demonstrating how to use AssertJ-JSON in various scenarios, modeled after our own test suite.
+
+## Example 1: Asserting on a JSON String
+
+The most basic usage is parsing an inline JSON string and asserting on its properties.
+
+```java
+import static com.archyoshi.assertj.json.JsonAssertions.assertThat;
+import org.junit.jupiter.api.Test;
+
+class JsonStringTest {
+    @Test
+    void shouldParseJsonStringAndAssertFieldValue() {
+        String json = "{ \"name\": \"Vegeta\", \"age\": 30, \"active\": true }";
+
+        assertThat(json)
+            .hasField("name")
+            .hasValueForField("Vegeta", "name")
+            .hasField("age")
+            .hasValueForField(30, "age");
+    }
+}
+```
+
+## Example 2: Asserting with a Custom ObjectMapper
+
+By default, AssertJ-JSON creates a standard Jackson `ObjectMapper` to parse strings and files. However, you can pass your own configured `ObjectMapper` if you need custom deserialization logic.
+
+```java
+import static com.archyoshi.assertj.json.JsonAssertions.assertThat;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+class CustomMapperTest {
+    @Test
+    void shouldUseProvidedObjectMapperForStringParsing() {
+        ObjectMapper mapper = new ObjectMapper();
+        // Configure mapper here...
+
+        assertThat("{ \"name\": \"Goku\" }", mapper)
+            .hasValueForField("Goku", "name");
+    }
+}
+```
+
+## Example 3: Asserting directly on `JsonNode`
+
+If your code under test already returns a Jackson `JsonNode` or `ObjectNode`, you can pass it directly to `assertThat` without needing to serialize it to a string first.
+
+```java
+import static com.archyoshi.assertj.json.JsonAssertions.assertThat;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import org.junit.jupiter.api.Test;
+
+class JsonNodeTest {
+    @Test
+    void shouldAssertOnJsonNode() {
+        ObjectMapper mapper = new ObjectMapper();
+        ObjectNode node = mapper.createObjectNode();
+        node.put("name", "Goku");
+
+        assertThat(node)
+            .hasField("name")
+            .hasValueForField("Goku", "name");
+    }
+}
+```
+
+## Example 4: Asserting on Files and Paths
+
+You can assert that a file's contents match an expected JSON structure. You can use either `java.io.File` or `java.nio.file.Path`.
+
+```java
+import static com.archyoshi.assertj.json.JsonAssertions.assertThat;
+import java.io.File;
+import java.nio.file.Path;
+import java.nio.file.Files;
+import org.junit.jupiter.api.Test;
+
+class FileTest {
+    @Test
+    void shouldAssertOnFileDirectly() throws Exception {
+        Path actualPath = Files.createTempFile("actual-", ".json");
+        Files.writeString(actualPath, "{\"name\":\"Vegeta\"}");
+        File actualFile = actualPath.toFile();
+
+        // You can check that the fields match an expected JSON string
+        assertThat(actualFile)
+            .hasSameFieldsAs("{\"name\":\"Goku\"}");
+    }
+
+    @Test
+    void shouldAssertOnPathAndCompareContent() throws Exception {
+        Path actual = Files.createTempFile("actual-", ".json");
+        Path expected = Files.createTempFile("expected-", ".json");
+        Files.writeString(actual, "{ \"name\": \"Goku\" }");
+        Files.writeString(expected, "{\n  \"name\": \"Goku\"\n}");
+
+        // Compare two Paths ignoring formatting
+        assertThat(actual).hasSameContentAs(expected);
+    }
+}
+```