From a4ea0bb64457457bb267adfd641dc2779a02d530 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20Caldero=CC=81n?= Date: Mon, 30 Mar 2026 13:30:43 +0200 Subject: [PATCH 1/2] Add AGENTS.md, CODEOWNERS, and PR template for agent-first readiness - AGENTS.md: documents repo structure, content types, contribution workflows, commands, and rules for AI agents and contributors - CODEOWNERS: assigns Dev Rel as default reviewers, Web team as backup for web/ and playground/ directories - PR template: standardized checklist for contributions Part of the agent-first repos initiative. Refs: https://github.com/PSPDFKit/awesome-nutrient/issues/187 --- .github/CODEOWNERS | 6 ++ .github/pull_request_template.md | 20 ++++++ AGENTS.md | 108 +++++++++++++++++++++++++++++++ 3 files changed, 134 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..2223c8e2 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,6 @@ +# Default: Dev Rel owns this repo +* @PSPDFKit/dev-rel + +# Web SDK examples — Web team as backup reviewers +/web/ @PSPDFKit/dev-rel @PSPDFKit/nickel +/playground/ @PSPDFKit/dev-rel @PSPDFKit/nickel diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..728ffb09 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,20 @@ +## What + + + +## Type + + +- [ ] New playground snippet +- [ ] New local example +- [ ] New external link / resource +- [ ] Update to existing content +- [ ] Repo infrastructure (CI, docs, tooling) + +## Checklist + +- [ ] `npm run format` passes +- [ ] README updated (category index and/or root README) +- [ ] Example has a `README.md` with description and quick start (if local example) +- [ ] Example runs successfully with `npm start` (if local example) +- [ ] No duplicate content (not both playground snippet and local example for same feature) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..b0978500 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,108 @@ +# Agent Guide: awesome-nutrient + +Curated collection of Nutrient SDK examples, demos, and resources. +This is **not** an SDK — it's showcase and educational content. + +## Repository Structure + +``` +awesome-nutrient/ +├── web/ # Local runnable Web SDK examples +│ ├── annotation/ # Annotation demos (comment, clipboard, watermark…) +│ ├── signing/ # Signing demos (digital signatures, sign-here…) +│ ├── document-editor/ # Page manipulation demos +│ ├── document-generator-vanillajs/ # Document Authoring SDK generator +│ ├── viewer/ # Multi-tab viewer +│ ├── ui-customization/ # Baseline UI customization +│ ├── ui-customization-doc-editor-sidebar/ +│ └── miscellaneous/ # Analytics integrations +├── playground/ # Interactive Playground snippets +│ ├── annotations/ # Snippet folders (TypeScript + MDX) +│ ├── comments/ +│ ├── content-editor/ +│ ├── document-editor/ +│ ├── form-creator/ +│ ├── forms/ +│ ├── redaction/ +│ ├── signatures/ +│ ├── text-comparison/ +│ ├── toolbar-menus/ +│ ├── viewer/ +│ ├── shared/ # Shared utilities for snippets +│ ├── types/ # TypeScript type definitions +│ └── web-*.md # Category index files with Playground URLs +├── dws/ # Document Web Services example (React + Vite) +├── document-engine/ # Deployment examples (Terraform, Kubernetes) +├── document-authoring/ # Document Authoring SDK examples +├── gdpicture/ # GdPicture examples (.NET) +├── android/ # Android examples (placeholder) +├── ios/ # iOS examples (placeholder) +├── windows/ # Windows WinUI3 example +└── README.md # Main index linking to everything +``` + +## Content Types + +Choose the right format for your contribution: + +| Type | When to Use | Location | +|------|------------|----------| +| **Playground snippet** | Small, single-feature demos (<100 lines). Runs in the browser with zero setup. | `playground///` | +| **Local example** | Multi-file projects that need `npm install`. More complex demos. | `web///` | +| **External link** | References to other repos, docs, or third-party integrations. | `README.md` | + +## Adding a Playground Snippet + +Each snippet lives in `playground///` with two files: + +1. **`index.ts`** — The TypeScript code that runs in the Playground +2. **`playground.mdx`** — MDX file with metadata and description + +After creating the snippet folder: +- Add an entry in the corresponding `playground/web-.md` index file +- The entry should include a Playground URL with the base64-encoded snippet + +## Adding a Local Web Example + +1. Create `web///` +2. Include at minimum: + - `package.json` with a `start` script + - `index.html` + - `index.js` (or `index.ts`) + - A sample PDF if needed (`document.pdf`) +3. Add a `README.md` in the example folder with description and quick start +4. Add an entry in `web//README.md` +5. If it's a new category, add it to the root `README.md` + +## Commands + +```bash +# Install dependencies (root — formatter + linting) +npm install + +# Format all code with Biome +npm run format + +# Run lint-staged checks (runs automatically on commit via Husky) +npm run lint-staged +``` + +## Code Style + +- **Biome** handles formatting and linting. Run `npm run format` before committing. +- Husky pre-commit hook runs `lint-staged` automatically. +- CI runs Biome checks on every push and PR. + +## Rules + +- All code must pass Biome formatting +- Every local example must have a working `npm start` +- Keep README sections ordered by category +- Don't duplicate content — a feature should be either a playground snippet OR a local example, not both +- Use `@nutrient-sdk/viewer` (not legacy `pspdfkit`) for new Web SDK examples +- Include a `README.md` with description and quick-start instructions in every example folder + +## CI + +- **Biome** (`byome.yml`) — Code formatting and lint checks +- **Typecheck** (`typecheck.yml`) — TypeScript validation for playground snippets From 8fc631da00f0c99b4332189cf47a0b1b66f94219 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20Caldero=CC=81n?= Date: Mon, 30 Mar 2026 14:19:12 +0200 Subject: [PATCH 2/2] Fix AGENTS.md tree: add missing resources/, playground config files --- AGENTS.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b0978500..9db938fc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,11 +30,15 @@ awesome-nutrient/ │ ├── viewer/ │ ├── shared/ # Shared utilities for snippets │ ├── types/ # TypeScript type definitions -│ └── web-*.md # Category index files with Playground URLs +│ ├── web-*.md # Category index files with Playground URLs +│ ├── README.md +│ ├── package.json # Snippet typechecking workspace +│ └── tsconfig.json ├── dws/ # Document Web Services example (React + Vite) ├── document-engine/ # Deployment examples (Terraform, Kubernetes) ├── document-authoring/ # Document Authoring SDK examples ├── gdpicture/ # GdPicture examples (.NET) +├── resources/ # Shared assets (PDFs, images) ├── android/ # Android examples (placeholder) ├── ios/ # iOS examples (placeholder) ├── windows/ # Windows WinUI3 example