feat: create v6 articles (#758)

Co-authored-by: Pavel Denisjuk <pavel@webiny.com>
Co-authored-by: Bruno Zorić <bruno.zoric@gmail.com>
Co-authored-by: Swapnil M Mane <swapnilmmane@gmail.com>
Co-authored-by: SvenAlHamad <sven@webiny.com>

Author: 5 people

.gitignore

@@ -123,6 +123,11 @@ build
 /src/data/
 /src/pages/docs/
 /public/algolia/sitemap.xml
-
+/public/docs-static/raw/
 # Mac files
 .DS_Store
+
+# Bruno
+v6
+remote
+.claude/settings.local.json

.mdx-validation.json

@@ -0,0 +1,11 @@
+{
+  "targetDir": "docs/developer-docs/6.0.x",
+  "exceptions": [
+    "get-started/welcome.mdx",
+    "get-started/install-webiny.mdx",
+    "overview/pricing.mdx",
+    "overview/features/security.mdx",
+    "tenant-manager/manage-tenants.mdx",
+    "tenant-manager/extend-tenant-model.mdx"
+  ]
+}

AGENTS.md

@@ -0,0 +1,258 @@
+# Project Instructions
+
+## Critical Project Conventions
+
+### Package Manager
+
+- **ALWAYS use `yarn`, NEVER use `npm`** - This project exclusively uses Yarn
+- All script execution: `yarn <script-name>`
+- All package operations: `yarn add`, `yarn install`, etc.
+
+### Validation and Quality
+
+- **MDX/.ai.txt Pairing**: Every `.mdx` file must have a corresponding `.ai.txt` companion file
+- Run `yarn validate:mdx` to verify pairing before commits/PRs
+- Exceptions are defined in `.mdx-validation.json` (supports exact paths and glob patterns)
+- The validation script (`scripts/validate-mdx-pairing.ts`) checks bidirectionally
+
+### Project Structure
+
+- Documentation: `docs/developer-docs/6.0.x/`
+- Plans/design docs: `plans/` (project root)
+- Scripts: `scripts/` (TypeScript scripts executed via `tsx`)
+- Validation config: `.mdx-validation.json` (project root)
+
+## Documentation Structure
+
+- Documentation files live in `docs/developer-docs/6.0.x/`
+- `.mdx` files are the documentation pages
+- `.ai.txt` files are AI companion context files — read them to understand the corresponding `.mdx` file (sources, decisions, patterns, tone guidelines)
+
+### Directory Layout
+
+```
+docs/developer-docs/6.0.x/
+├── core-concepts/      # Foundational knowledge: architecture, applications, project structure, DI, Result pattern, multi-tenancy, local dev, env vars
+├── get-started/        # Welcome, installation, upgrade to Business
+├── cli/                # CLI commands reference
+├── graphql/            # GraphQL schema building with factory pattern
+├── headless-cms/       # Largest section — all CMS extensibility
+│   ├── builder/        # ModelBuilder, GroupBuilder, FieldBuilder APIs
+│   ├── event-handler/  # Entry/model/group lifecycle events
+│   ├── examples/       # Private model, single-entry model
+│   ├── ui/             # Field renderers
+│   └── use-case/       # Entry/model/group business logic
+├── overview/           # Pricing, security features
+│   └── features/
+├── tasks/              # Background task system (Runner, Context, Controller)
+└── website-builder/    # Website Builder extensibility
+    ├── event-handler/  # Page/redirect lifecycle events
+    └── use-case/       # Page/redirect business logic
+```
+
+### Key Patterns
+
+- Each major system follows a consistent taxonomy: **builder** (define structure) / **event-handler** (react to events) / **use-case** (custom business logic)
+- `core-concepts/di.mdx` and `core-concepts/result.mdx` are foundational — referenced by all other sections
+- `.ai.txt` files contain: source info, key decisions, understanding, code patterns, related docs, and tone guidelines
+- Tone is calibrated per doc type: conceptual (about), technical (reference), practical (examples)
+
+### MDX/.ai.txt Pairing Exceptions
+
+Current exceptions (defined in `.mdx-validation.json`):
+
+- `get-started/welcome.mdx` - introductory page
+- `get-started/install-webiny.mdx` - installation guide
+- `overview/pricing.mdx` - pricing overview
+- `overview/features/security.mdx` - security features
+
+## MDX Writing Conventions
+
+### Frontmatter
+
+Every `.mdx` file uses exactly three required fields:
+
+```yaml
+---
+id: <8-char-alphanumeric> # e.g., "kp9m2xnf" — short, random, lowercase
+title: <Title Case>
+description: <One-line description>
+---
+```
+
+Optional fields (rare, only for special pages like welcome): `pageHeader: false`, `fullWidth: true`.
+
+### Page Structure
+
+Every page follows this order:
+
+1. Frontmatter
+2. Component imports
+3. `<Alert type="success" title="WHAT YOU'LL LEARN">` block with bullet list of questions
+4. `## Overview` — always the first H2, 1-3 paragraphs of prose
+5. Content sections as H2 (`##`) with H3 (`###`) subsections as needed
+6. No H1 headings in the body — the page title comes from frontmatter
+
+### Components
+
+Only one MDX component is used: `<Alert>` from `@/components/Alert`.
+
+```mdx
+import { Alert } from "@/components/Alert";
+
+;
+```
+
+Alert types:
+
+- `type="success"` — "WHAT YOU'LL LEARN" opener (every page)
+- `type="info"` — supplemental links or context (inline, overview pages)
+- `type="warning"` — important cautions (inline, overview pages)
+
+No other custom components are used (no `<Tabs>`, `<Steps>`, etc.).
+
+### Code Blocks
+
+- Language tag is always specified: ` ```typescript ` or ` ```graphql `
+- **File path annotations** go after the language tag: ` ```typescript extensions/cms/group/eventHandler/create/beforeCreate.ts `
+- Use ` ```tsx ` for `webiny.config.tsx` files
+- GraphQL SDL in TypeScript uses `/* GraphQL */` tag: `builder.addTypeDefs(/* GraphQL */ \`...\`)`
+- Minimal comments in code — only for pedagogical correct/wrong comparisons using `// ✅ Correct` / `// ❌ Wrong`
+- No shell/bash code blocks
+
+### Import Paths in Code Examples
+
+```typescript
+// Webiny v6 API imports — use "webiny/" prefix, NOT "@webiny/"
+import { ModelFactory } from "webiny/api/cms/model";
+import { CreateEntryUseCase } from "webiny/api/cms/entry";
+import { Logger } from "webiny/api/logger";
+import { Api } from "webiny/extensions";
+import { Result } from "webiny/api";
+
+// Local file imports use .js extensions (ESM)
+import { BookRepository } from "./abstractions/BookRepository.js";
+
+// Type-only imports
+import type { CmsEntry } from "webiny/api";
+```
+
+### Text Formatting
+
+- Backticks for: code, class names, method names, type names, package names
+- **Bold** for key labels: `**Naming Convention:**`, `**Key Point:**`
+- Bullet lists use `-`, not numbered lists (even for sequential steps)
+- No emojis in prose
+- Inline links use standard markdown: `[text](/docs/path)`
+- "Webiny" always capitalized
+
+## Tone and Voice
+
+### General Rules
+
+- Concise and technical — no filler, no marketing language in developer docs
+- Direct and instructional — "Use `createAbstraction()` to create one"
+- Address the reader as "you"
+- Explain "why" briefly before showing "how"
+- Avoid "we" statements — use "The system provides/offers" instead
+- No analogies in published docs (save those for `.ai.txt` context)
+- Accessible to junior developers while remaining technically complete
+
+### Per Doc Type
+
+| Doc Type                    | Tone                         | Focus                                             |
+| --------------------------- | ---------------------------- | ------------------------------------------------- |
+| `about.mdx`                 | Conceptual, accessible       | Why and what, link to reference for how           |
+| `reference.mdx`             | Simple, concise, API-focused | Method signatures, minimal examples               |
+| `example.mdx`               | Practical, production-ready  | Complete working code, copy-paste friendly        |
+| `event-handler/*.mdx`       | Production-ready examples    | When/why to use each event, real-world scenarios  |
+| `use-case/*.mdx`            | Technical and complete       | Full abstraction + implementation patterns        |
+| `builder/*.mdx`             | Technical reference          | Complete method docs, practical examples per type |
+| `management.mdx`            | Practical, operation-focused | Complete examples, error handling                 |
+| `get-started/`, `overview/` | Conversational, welcoming    | High-level survey, no code                        |
+
+## TypeScript Code Patterns
+
+### DI Pattern (used in all implementations)
+
+```typescript
+import { SomeAbstraction } from "webiny/api/cms/entity";
+import { Logger } from "webiny/api/logger";
+
+// Implementation class with Impl suffix
+class SomeAbstractionImpl implements SomeAbstraction.Interface {
+  public constructor(private logger: Logger.Interface) {}
+
+  public async handle(event: SomeAbstraction.Event): Promise<void> {
+    // implementation
+  }
+}
+
+// Factory registration — MUST be default export
+const SomeAbstractionConst = SomeAbstraction.createImplementation({
+  implementation: SomeAbstractionImpl,
+  dependencies: [Logger]
+});
+
+export default SomeAbstractionConst;
+```
+
+### Result Pattern (used in all use cases)
+
+```typescript
+const result = await someUseCase.execute(params);
+if (result.isFail()) {
+  // handle error — return early (guard clause)
+  return { error: result.error, data: null };
+}
+const value = result.value;
+```
+
+### Namespace Export Pattern (abstractions)
+
+```typescript
+export namespace MyAbstraction {
+  export type Interface = IMyAbstraction;
+  export type Params = IMyAbstractionParams;
+  export type Return = IMyAbstractionReturn;
+}
+```
+
+### Registration in webiny.config.tsx
+
+```tsx
+import React from "react";
+import { Api } from "webiny/extensions";
+
+export const Extensions = () => {
+  return (
+    <>
+      {/* ... all your other extensions */}
+      <Api.Extension src={"/extensions/cms/entity/path/to/file.ts"} />
+    </>
+  );
+};
+```
+
+### Event Handler Naming
+
+- Class names: `On[Resource][Before|After][Operation]Handler` (e.g., `OnPageBeforeCreateHandler`)
+- Abstraction tokens: `[Resource][Before|After][Operation]Handler` (without "On" prefix)
+- "Before" handlers receive `payload.input`; "After" handlers receive the completed entity (e.g., `payload.page`)
+
+## .ai.txt File Format
+
+Each `.ai.txt` companion file contains these sections:
+
+1. `AI Context: [Page Title] ([filename])` — header
+2. `Source of Information:` — numbered list of research sources
+3. `Key Documentation Decisions:` — editorial choices made
+4. `[Topic-specific understanding]` — detailed domain knowledge
+5. `[Code patterns/snippets]` — verified TypeScript templates
+6. `Related Documents:` — cross-references to sibling docs
+7. `Key Code Locations:` — source code paths in the Webiny repo
+8. `Tone Guidelines:` — explicit style instructions for the page
+
+### Maintenance
+
+- When new documentation files (`.mdx` or `.ai.txt`) are added, update the directory layout and notes in this AGENTS.md to reflect the changes.

CLAUDE.md

@@ -0,0 +1,3 @@
+## Startup
+- Always read `~/.claude/settings.json` at the start of every conversation.
+- Read `./AGENTS.md"

docs.config.ts

@@ -34,27 +34,78 @@ const linkWhitelist: string[] = [...redirects.map(r => r.source), "/forms/produc
  */
 const whitelistedVersions: string[] = [];
 
+/**
+ * Only build versions at or above this version (e.g., "5.40.x").
+ * Set via MIN_VERSION environment variable or modify here.
+ * Set to empty string to build all versions.
+ */
+const minVersionToBuild = process.env.MIN_VERSION || "";
+
 const filterByEnvironment = (version: Version) => {
   // In `preview`, if there are specific versions whitelisted for deployment, those are the only ones we'll output.
   if (preview && whitelistedVersions.length > 0) {
     return whitelistedVersions.includes(version.getValue());
   }
 
+  // If minVersionToBuild is set, only build versions >= minVersion or `latest`.
+  if (minVersionToBuild) {
+    if (minVersionToBuild === "latest") {
+      return version.isLatest();
+    }
+    const versionNum = parseFloat(version.getValue().replace(/[^\d.]/g, ""));
+    const minVersionNum = parseFloat(minVersionToBuild.replace(/[^\d.]/g, ""));
+    return versionNum >= minVersionNum;
+  }
+
   // Build everything.
   return true;
 };
 
+const filterFilePathByVersion = (filePath: string): boolean => {
+  // Extract version from file path (e.g., /docs/developer-docs/5.40.x/... or /docs/user-guides/5.40.x/...)
+  const versionMatch = filePath.match(/\/(\d+\.\d+\.x)\//);
+
+  if (!versionMatch) {
+    // If no version in path, include the file (e.g., non-versioned docs)
+    return true;
+  }
+
+  const versionString = versionMatch[1];
+
+  // Use the same filtering logic as filterByEnvironment
+  if (preview && whitelistedVersions.length > 0) {
+    return whitelistedVersions.includes(versionString);
+  }
+
+  if (minVersionToBuild) {
+    if (minVersionToBuild === "latest") {
+      // For file paths, we can't determine if it's "latest" without more context
+      // So we'll include all versioned files when minVersionToBuild is "latest"
+      return true;
+    }
+    const versionNum = parseFloat(versionString.replace(/[^\d.]/g, ""));
+    const minVersionNum = parseFloat(minVersionToBuild.replace(/[^\d.]/g, ""));
+    return versionNum >= minVersionNum;
+  }
+
+  return true;
+};
+
 const existsInDocs = (link: string) => {
   return fs.pathExists(path.join(__dirname, `src/pages/${link}.js`));
 };
 
 export default {
   projectRootDir: __dirname,
-  cleanOutputDir: path.resolve("src/pages/docs"),
+  cleanOutputDir: [path.resolve("src/pages/docs"), path.resolve("public/raw/docs")],
   sitemapOutputPath: path.resolve("public/algolia/sitemap.xml"),
-  linkValidator: new LinkValidator(linkWhitelist, link => {
-    return existsInDocs(link);
-  }),
+  linkValidator: new LinkValidator(
+    linkWhitelist,
+    link => {
+      return existsInDocs(link);
+    },
+    filterFilePathByVersion
+  ),
   documentRoots: [
     /* Developer Docs */
     new VersionedDocumentRootConfig({

docs/developer-docs/5.28.x/core-development-concepts/scaffolding/react-application.mdx

@@ -227,7 +227,7 @@ import { createWatchApp, createBuildApp } from "@webiny/project-utils";
 
 // Exports fundamental watch and build commands.
 // Need to inject environment variables or link your application with an existing GraphQL API?
-// See https://www.webiny.com/docs/core-development-concepts/scaffolding/full-stack-application/webiny-config.
+// See https://www.webiny.com/docs/{version}/core-development-concepts/scaffolding/full-stack-application/webiny-config.
 export default {
   commands: {
     async watch(options, context) {

docs/developer-docs/5.28.x/custom-app-tutorial/adding-user-pools/adding-user-pool-and-user-pool-domain.mdx

@@ -124,7 +124,7 @@ import Cloudfront from "./cloudfront";
 const DEBUG = String(process.env.DEBUG);
 
 // Enables logs forwarding.
-// https://www.webiny.com/docs/core-development-concepts/basics/watch-command#enabling-logs-forwarding
+// https://www.webiny.com/docs/{version}/core-development-concepts/basics/watch-command#enabling-logs-forwarding
 const WEBINY_LOGS_FORWARD_URL = String(process.env.WEBINY_LOGS_FORWARD_URL);
 
 export default () => {

docs/developer-docs/5.28.x/custom-app-tutorial/securing-graphql-api/initial-setup.mdx

@@ -73,7 +73,7 @@ import Cognito from "./cognito";
 import S3 from "./s3";
 
 // Among other things, this determines the amount of information we reveal on runtime errors.
-// https://www.webiny.com/docs/core-development-concepts/environment-variables/#debug-environment-variable
+// https://www.webiny.com/docs/{version}/core-development-concepts/environment-variables/#debug-environment-variable
 const DEBUG = String(process.env.DEBUG);
 
 // Enables logs forwarding.