RDoc-3729 Add Samples to documentation

CLAUDE.md

@@ -135,11 +135,103 @@ Each folder contains `_category_.json`:
 
 ---
 
+## Frontmatter Naming Convention
+**CRITICAL RULE**: All custom frontmatter fields MUST use `snake_case`. Never use camelCase for custom frontmatter.
+- ✅ Correct: `published_at`, `proficiency_level`, `external_url`, `img_alt`, `repository_url`, `license_url`
+- ❌ Wrong: `publishedAt`, `proficiencyLevel`, `externalUrl`, `imgAlt`, `repositoryUrl`, `licenseUrl`
+- Standard Docusaurus fields (e.g., `title`, `description`, `slug`) remain as-is.
+- Tag values in guides and samples MUST use `kebab-case` (e.g., `vector-search`, `azure-storage-queues-etl`).
+
+---
+
 ## Guides
 - Tags defined in `guides/tags.yml` (~40 predefined tags — do not invent new ones without adding there first).
-- Guide-specific frontmatter: `tags`, `description`, `icon`, `image`, `publishedAt` (ISO date), `externalUrl`.
+- Guide-specific frontmatter: `tags`, `description`, `icon`, `image`, `published_at` (ISO date), `external_url`, `proficiency_level`, `author`.
 - Indexed and sorted by `src/plugins/recent-guides-plugin.ts`.
 
+### Guides Frontmatter Example
+```yaml
+---
+title: "Guide Title"
+published_at: 2026-04-02
+author: "Author Name"
+tags: [ai, vector-search, getting-started]
+description: "Short description shown in cards."
+image: "/img/guides-example.webp"
+proficiency_level: "Beginner"
+---
+```
+
+For external guides (linking to blog posts):
+```yaml
+---
+title: "External Article Title"
+published_at: 2026-04-02
+tags: [integration]
+description: "Short description."
+external_url: "https://ravendb.net/articles/example"
+image: "https://ravendb.net/path/to/image.jpg"
+---
+```
+
+---
+
+## Samples
+- Production-ready code samples demonstrating RavenDB features and architecture patterns.
+- Located in `samples/` directory.
+- Three-category tag system: Challenges & Solutions, Features, Tech Stack.
+- Tags defined in `samples/tags/` YAML files — do not invent new ones without adding there first.
+- Indexed by `src/plugins/recent-samples-plugin.ts`.
+- Hub page at `/samples` with filtering by tags.
+
+### Sample Tag Categories
+1. **Challenges & Solutions** (`samples/tags/challenges-solutions.yml`) - Business problems the sample solves
+   - Examples: `semantic-search`, `integration-patterns`, `cloud-tax`, `gen-ai-data-enrichment`
+
+2. **Features** (`samples/tags/feature.yml`) - RavenDB features demonstrated
+   - Examples: `vector-search`, `document-refresh`, `include`, `azure-storage-queues-etl`
+
+3. **Tech Stack** (`samples/tags/tech-stack.yml`) - Technologies used
+   - Examples: `csharp`, `aspire`, `azure-functions`, `nodejs`, `nextjs`
+
+### Sample Frontmatter Example
+```yaml
+---
+title: "Sample Application Name"
+description: "Brief description for sample cards."
+challenges_solutions_tags: [semantic-search, integration-patterns]
+feature_tags: [vector-search, document-refresh, include]
+tech_stack_tags: [csharp, aspire, azure-functions]
+image: "/img/samples/my-sample/cover.webp"
+img_alt: "Screenshot of the application"
+category: "Ecommerce"
+license: "MIT License"
+license_url: "https://opensource.org/licenses/MIT"
+repository_url: "https://github.com/ravendb/sample-repo"
+demo_url: "https://demo.example.com"
+languages: ["C#"]
+gallery:
+  - src: "/img/samples/my-sample/screenshot-1.webp"
+    alt: "Main interface"
+  - src: "/img/samples/my-sample/screenshot-2.webp"
+    alt: "Admin dashboard"
+related_resources:
+  - type: documentation
+    documentation_type: docs
+    subtitle: "Vector Search Overview"
+    article_key: "ai-integration/vector-search/overview"
+  - type: guide
+    subtitle: "Related Guide Title"
+    article_key: "guide-slug"
+---
+```
+
+**Required fields**: `title`, `description`, `challenges_solutions_tags`, `feature_tags`, `tech_stack_tags`
+
+**Optional fields**: `image`, `img_alt`, `category`, `license`, `license_url`, `repository_url`, `demo_url`, `languages`, `gallery`, `related_resources`
+
+**SEO**: `repository_url` and `languages` feed `SoftwareSourceCode` JSON-LD schema for better search visibility.
+
 ---
 
 ## Icon System
@@ -377,11 +469,31 @@ Each folder contains `_category_.json`:
 ### `cloud/` — RavenDB Cloud service documentation (~24 files)
 Account management, instance configuration, security (TLS, MFA, certificates), pricing/billing, scaling, backup/restore, migration, AWS/Azure Marketplace setup, and the cloud portal UI (home, products, billing, backups, support tabs).
 
-### `guides/` — Practical how-to guides (~63 files, flat structure)
-Community guides covering: connecting specific frameworks (ASP.NET Core, Next.js, SvelteKit, FastAPI), AI/ML integration, DevOps (Docker, Kubernetes/EKS, Helm, Ansible), observability (Datadog, Grafana/OpenTelemetry), data pipelines (Elasticsearch, Azure Queue, OLAP ETL), testing (unit test drivers for .NET/Java/Python), and troubleshooting specific problems. Tags defined in `guides/tags.yml`.
+### `guides/` — Practical how-to guides (~64 files, flat structure)
+Community guides covering: connecting specific frameworks (ASP.NET Core, Next.js, SvelteKit, FastAPI), AI/ML integration, DevOps (Docker, Kubernetes/EKS, Helm, Ansible), observability (Datadog, Grafana/OpenTelemetry), data pipelines (Elasticsearch, Azure Queue, OLAP ETL), testing (unit test drivers for .NET/Java/Python), and troubleshooting specific problems.
+
+**Frontmatter**: `title`, `published_at`, `author`, `tags`, `description`, `icon`, `image`, `proficiency_level`, `external_url` (for external guides).
+
+**Tags**: Defined in `guides/tags.yml` (~40 predefined tags — do not invent new ones without adding there first). All tag values use kebab-case.
+
+**Indexed by**: `src/plugins/recent-guides-plugin.ts`
+
+### `samples/` — Production-ready code samples (~1+ files)
+Production-ready code samples, architecture patterns, and starter kits demonstrating RavenDB features and integration scenarios. Hub page at `/samples` with tag-based filtering.
+
+**Frontmatter**: `title`, `description`, `challenges_solutions_tags`, `feature_tags`, `tech_stack_tags`, `image`, `img_alt`, `category`, `license`, `license_url`, `repository_url`, `languages`, `gallery`.
+
+**Tags**: Three categories defined in `samples/tags/`:
+- `challenges-solutions.yml` - Business problems solved (e.g., `semantic-search`, `integration-patterns`)
+- `feature.yml` - RavenDB features demonstrated (e.g., `vector-search`, `document-refresh`)
+- `tech-stack.yml` - Technologies used (e.g., `csharp`, `aspire`, `azure-functions`)
+
+All tag values use kebab-case.
+
+**Indexed by**: `src/plugins/recent-samples-plugin.ts`
 
 ### `templates/` — Authoring reference templates (~9 files)
-Style guide and live examples for documentation building blocks: ContentFrame/Panel layouts, icon gallery, themed images, tag reference, see-also cross-links, featured/new guide blocks.
+Style guide and live examples for documentation building blocks: ContentFrame/Panel layouts, icon gallery, themed images, tag reference, see-also cross-links, featured/new guide blocks, sample authoring templates.
 
 ---
 

cloud/home.mdx

@@ -2,7 +2,7 @@
 slug: /
 pagination_next: null
 pagination_prev: null
-wrapperClassName: cloud-home-page
+wrapperClassName: cloudHomePage
 hide_table_of_contents: true
 ---
 

docs/home.mdx

@@ -3,7 +3,7 @@ slug: /
 title: "Guides, API Reference & Tutorials"
 pagination_next: null
 pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
 hide_table_of_contents: true
 description: "Official RavenDB documentation. Guides for installation, client APIs, indexing, querying, AI integration, clustering, security, and the Studio UI across all supported versions."
 keywords:

docusaurus.config.ts

@@ -123,6 +123,15 @@ const config: Config = {
                 showLastUpdateTime: true,
             },
         ],
+        [
+            "content-docs",
+            {
+                id: "samples",
+                path: "samples",
+                routeBasePath: "samples",
+                sidebarPath: require.resolve("./sidebarsSamples.js"),
+            },
+        ],
         [
             "@docusaurus/plugin-ideal-image",
             {
@@ -134,6 +143,7 @@ const config: Config = {
             },
         ],
         require.resolve("./src/plugins/recent-guides-plugin"),
+        require.resolve("./src/plugins/recent-samples-plugin"),
     ],
     headTags: [
         {

eslint.config.js

@@ -74,7 +74,7 @@ module.exports = [
             "@typescript-eslint/no-explicit-any": "off",
             "@typescript-eslint/prefer-namespace-keyword": "off",
 
-            "no-console": "warn",
+            "no-console": ["warn", { allow: ["warn", "error"] }],
             "no-debugger": "error",
             "no-alert": "warn",
             "no-var": "error",
@@ -101,6 +101,12 @@ module.exports = [
             "no-undef": "off",
         },
     },
+    {
+        files: ["**/*.ts", "**/*.tsx"],
+        rules: {
+            "no-undef": "off",
+        },
+    },
     {
         ignores: [
             "node_modules/",

guides/ai-image-search-with-ravendb.mdx

@@ -2,9 +2,9 @@
 title: "AI Image Search with RavenDB"
 tags: [ai, csharp, demo, use-case]
 description: "Read about AI Image Search with RavenDB on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/ai-image-search-with-ravendb"
-publishedAt: 2025-09-09 
+external_url: "https://ravendb.net/articles/ai-image-search-with-ravendb"
+published_at: 2025-09-09 
 icon: "ai"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---
 

guides/begin-analysis-with-olap-etl.mdx

@@ -2,9 +2,9 @@
 title: "Begin Analysis with OLAP ETL"
 tags: [integration, background-tasks, architecture, use-case]
 description: "Read about Begin Analysis with OLAP ETL on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/begin-analysis-with-olap-etl"
-publishedAt: 2025-12-22
+external_url: "https://ravendb.net/articles/begin-analysis-with-olap-etl"
+published_at: 2025-12-22
 image: "https://ravendb.net/wp-content/uploads/2025/12/OLAP-article-image.svg"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---
 

guides/building-a-beer-vending-machine-program-with-ravendb-embedded-server.mdx

@@ -2,9 +2,9 @@
 title: "Building a Beer Vending Machine with RavenDB Embedded"
 tags: [demo, getting-started]
 description: "Read about Building a Beer Vending Machine with RavenDB Embedded on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/building-a-beer-vending-machine-program-with-ravendb-embedded-server"
-publishedAt: 2025-12-23
+external_url: "https://ravendb.net/articles/building-a-beer-vending-machine-program-with-ravendb-embedded-server"
+published_at: 2025-12-23
 image: "https://ravendb.net/wp-content/uploads/2024/11/article-beer-2.jpg"
-proficiencyLevel: "Beginner"
+proficiency_level: "Beginner"
 ---
 

guides/connecting-c-application-to-ravendb-cloud.mdx

@@ -2,8 +2,8 @@
 title: "Connecting C# application to RavenDB Cloud"
 tags: [csharp, getting-started]
 description: "Read about Connecting C# application to RavenDB Cloud on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/connecting-c-application-to-ravendb-cloud"
-publishedAt: 2025-02-25
+external_url: "https://ravendb.net/articles/connecting-c-application-to-ravendb-cloud"
+published_at: 2025-02-25
 image: "https://ravendb.net/wp-content/uploads/2025/01/connecting-c-application-article-cover.jpg"
-proficiencyLevel: "Beginner"
+proficiency_level: "Beginner"
 ---

guides/connecting-node-js-application-to-ravendb-cloud.mdx

@@ -2,8 +2,8 @@
 title: "Connecting Node.js application to RavenDB Cloud"
 tags: [nodejs, getting-started]
 description: "Read about Connecting Node.js application to RavenDB Cloud on the RavenDB.net news section."
-externalUrl: "https://ravendb.net/articles/connecting-node-js-application-to-ravendb-cloud"
-publishedAt: 2025-02-25
+external_url: "https://ravendb.net/articles/connecting-node-js-application-to-ravendb-cloud"
+published_at: 2025-02-25
 image: "https://ravendb.net/wp-content/uploads/2025/01/connecting-nodejs-to-ravendb-article-cover.jpg"
-proficiencyLevel: "Beginner"
+proficiency_level: "Beginner"
 ---

guides/connecting-node-js-web-application-to-ravendb.mdx

@@ -2,8 +2,8 @@
 title: "Connecting Node.JS web application to RavenDB"
 tags: [nodejs, getting-started]
 description: "Read about Connecting Node.JS web application to RavenDB on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/connecting-node-js-web-application-to-ravendb"
-publishedAt: 2025-02-25
+external_url: "https://ravendb.net/articles/connecting-node-js-web-application-to-ravendb"
+published_at: 2025-02-25
 image: "https://ravendb.net/wp-content/uploads/2024/12/NodeJS-article-cover.jpg"
-proficiencyLevel: "Beginner"
+proficiency_level: "Beginner"
 ---

guides/deploying-ravendb-with-helm-chart.mdx

@@ -2,8 +2,8 @@
 title: "Deploying RavenDB with Helm Chart"
 tags: [deployment, kubernetes, docker, containers]
 description: "Read about Deploying RavenDB with Helm Chart on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/deploying-ravendb-with-helm-chart"
-publishedAt: 2025-11-18
+external_url: "https://ravendb.net/articles/deploying-ravendb-with-helm-chart"
+published_at: 2025-11-18
 image: "https://ravendb.net/wp-content/uploads/2025/05/helm-chart-article-cover.jpg"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---

guides/diacritic-sensitive-search-in-ravendb.mdx

@@ -2,9 +2,9 @@
 title: "Diacritic-Sensitive Search in RavenDB"
 tags: [demo, querying, use-case]
 description: "Read about Diacritic-Sensitive Search in RavenDB on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/diacritic-sensitive-search-in-ravendb"
-publishedAt: 2025-05-09
+external_url: "https://ravendb.net/articles/diacritic-sensitive-search-in-ravendb"
+published_at: 2025-05-09
 image: "https://ravendb.net/wp-content/uploads/2025/05/diacritic-sensitive-article.jpg"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---
 

guides/dynamic-fields.mdx

@@ -2,9 +2,9 @@
 title: "Dynamic Fields in RavenDB"
 tags: [deep-dive, indexes]
 description: "Read about Dynamic Fields in RavenDB on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/dynamic-fields"
-publishedAt: 2024-10-28
+external_url: "https://ravendb.net/articles/dynamic-fields"
+published_at: 2024-10-28
 image: "https://ravendb.net/wp-content/uploads/2024/10/dynamic-fields-cover.jpg"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---
 

guides/embeddings-generation-with-ravendb.mdx

@@ -2,9 +2,9 @@
 title: "Embeddings Generation with RavenDB"
 tags: [ai, use-case]
 description: "Read about Embeddings Generation with RavenDB on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/embeddings-generation-with-ravendb"
-publishedAt: 2025-03-31
+external_url: "https://ravendb.net/articles/embeddings-generation-with-ravendb"
+published_at: 2025-03-31
 image: "https://ravendb.net/wp-content/uploads/2025/03/ai-search-article-cover.jpg"
-proficiencyLevel: "Beginner"
+proficiency_level: "Beginner"
 ---
 

guides/employing-data-archival-guide.mdx

@@ -3,10 +3,10 @@ title: "Employing Data Archival"
 tags: [data-governance, csharp, use-case]
 icon: "real-time-statistics"
 image: "https://ravendb.net/wp-content/uploads/2025/10/employing-data-archival-article.svg"
-publishedAt: 2025-11-17
+published_at: 2025-11-17
 description: "How to set up and use data archival in RavenDB"
 author: "Paweł Lachowski"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---
 
 import Admonition from '@theme/Admonition';

guides/employing-schema-validation-to-standardize-your-data.mdx

@@ -3,9 +3,9 @@ title: "Employing Schema Validation to standardize your data"
 tags: [data-governance, csharp, use-case]
 icon: "document-schema"
 description: "Learn more about configuring schema validation in RavenDB to incrase trust in your data across teams."
-publishedAt: 2026-02-01
+published_at: 2026-02-01
 author: "Paweł Lachowski"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---
 
 import Admonition from '@theme/Admonition';

guides/enable-ai-search-in-your-web-app-in-5-minutes.mdx

@@ -2,9 +2,9 @@
 title: "Enable AI Search in Your Web App in 5 Minutes"
 tags: [ai, demo, nextjs, use-case]
 description: "Read about Enable AI Search in Your Web App in 5 Minutes on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/enable-ai-search-in-your-web-app-in-5-minutes"
-publishedAt: 2025-04-28
+external_url: "https://ravendb.net/articles/enable-ai-search-in-your-web-app-in-5-minutes"
+published_at: 2025-04-28
 image: "https://ravendb.net/wp-content/uploads/2025/04/enable-ai-search-cover.jpg"
-proficiencyLevel: "Beginner"
+proficiency_level: "Beginner"
 ---
 

guides/feed-elasticsearch-from-your-ravendb.mdx

@@ -2,9 +2,9 @@
 title: "Feed Elasticsearch from Your RavenDB"
 tags: [background-tasks, integration, architecture, use-case]
 description: "Read about Feed Elasticsearch from Your RavenDB on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/feed-elasticsearch-from-your-ravendb"
-publishedAt: 2025-12-14
+external_url: "https://ravendb.net/articles/feed-elasticsearch-from-your-ravendb"
+published_at: 2025-12-14
 image: "https://ravendb.net/wp-content/uploads/2025/12/elastic-search-article-image.png"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---
 

guides/full-lifecycle-automation-of-ravendb-with-ansible.mdx

@@ -2,9 +2,9 @@
 title: "Full Lifecycle Automation of RavenDB with Ansible"
 tags: [deployment, integration]
 description: "Read about Full Lifecycle Automation of RavenDB with Ansible on the RavenDB.net news section"
-externalUrl: "https://ravendb.net/articles/full-lifecycle-automation-of-ravendb-with-ansible"
-publishedAt: 2025-06-16
+external_url: "https://ravendb.net/articles/full-lifecycle-automation-of-ravendb-with-ansible"
+published_at: 2025-06-16
 image: "https://ravendb.net/wp-content/uploads/2025/06/Ansible-article-cover.jpg"
-proficiencyLevel: "Expert"
+proficiency_level: "Expert"
 ---