+
{description}
{(hasTags || hasDate) && (
-
+
{hasTags && (
{visibleTags.map((tag) => (
-
+
{tag.label}
))}
@@ -124,6 +122,7 @@ export default function CardWithImage({
expandTags();
}}
title="Show all tags"
+ className="pointer-events-auto"
>
+{hiddenCount} more
diff --git a/src/components/Common/CardWithImageHorizontal.tsx b/src/components/Common/CardWithImageHorizontal.tsx
index 3e4a52817e..3d24dd6521 100644
--- a/src/components/Common/CardWithImageHorizontal.tsx
+++ b/src/components/Common/CardWithImageHorizontal.tsx
@@ -10,7 +10,7 @@ import { clsx } from "clsx";
export interface CardWithImageHorizontalProps {
title: string;
description: ReactNode;
- imgSrc: string | { light: string; dark: string };
+ imgSrc: string;
imgAlt?: string;
url: string;
iconName?: IconName;
diff --git a/src/components/Common/Checkbox.tsx b/src/components/Common/Checkbox.tsx
new file mode 100644
index 0000000000..7f1e3a59a8
--- /dev/null
+++ b/src/components/Common/Checkbox.tsx
@@ -0,0 +1,36 @@
+import React, { ChangeEvent } from "react";
+import clsx from "clsx";
+import { Icon } from "./Icon";
+
+interface CheckboxProps {
+ checked: boolean;
+ onChange: (x: ChangeEvent) => void;
+ label?: string;
+ className?: string;
+}
+
+export default function Checkbox({ checked, onChange, label, className }: CheckboxProps) {
+ return (
+
+ );
+}
diff --git a/src/components/Common/Drawer.tsx b/src/components/Common/Drawer.tsx
new file mode 100644
index 0000000000..064870db3f
--- /dev/null
+++ b/src/components/Common/Drawer.tsx
@@ -0,0 +1,99 @@
+import React, { useEffect } from "react";
+import { motion, AnimatePresence, type PanInfo } from "motion/react";
+import clsx from "clsx";
+import { Icon } from "./Icon";
+
+interface DrawerProps {
+ open: boolean;
+ onClose: () => void;
+ children: React.ReactNode;
+ title?: string;
+ headerAction?: React.ReactNode;
+}
+
+export default function Drawer({ open, onClose, children, title, headerAction }: DrawerProps) {
+ useEffect(() => {
+ const handleEscape = (e: KeyboardEvent) => {
+ if (e.key === "Escape" && open) {
+ onClose();
+ }
+ };
+
+ document.addEventListener("keydown", handleEscape);
+ return () => document.removeEventListener("keydown", handleEscape);
+ }, [open, onClose]);
+
+ const handleDragEnd = (_: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => {
+ const shouldClose = info.velocity.y > 500 || info.offset.y > 150;
+ if (shouldClose) {
+ onClose();
+ }
+ };
+
+ return (
+
+ {open && (
+ <>
+
+
+
+ )}
+
+ );
+}
diff --git a/src/components/Common/Gallery.tsx b/src/components/Common/Gallery.tsx
new file mode 100644
index 0000000000..91b60d8f62
--- /dev/null
+++ b/src/components/Common/Gallery.tsx
@@ -0,0 +1,187 @@
+import React, { useRef, useState } from "react";
+import clsx from "clsx";
+import LazyImage from "./LazyImage";
+
+export interface GalleryImage {
+ src: string;
+ alt?: string;
+}
+
+export interface GalleryProps {
+ images: GalleryImage[];
+ className?: string;
+}
+
+export default function Gallery({ images, className }: GalleryProps) {
+ const thirdImageRef = useRef(null);
+ const [currentSlide, setCurrentSlide] = useState(0);
+ const carouselRef = useRef(null);
+
+ if (!images || images.length === 0) {
+ return null;
+ }
+
+ const visibleImages = images.slice(0, 3);
+ const remainingCount = Math.max(0, images.length - 3);
+
+ const handleOverlayClick = () => {
+ const imgElement = thirdImageRef.current?.querySelector("img");
+ if (imgElement) {
+ imgElement.click();
+ }
+ };
+
+ const handleScroll = () => {
+ if (carouselRef.current) {
+ const scrollLeft = carouselRef.current.scrollLeft;
+ const slideWidth = carouselRef.current.offsetWidth;
+ const newSlide = Math.round(scrollLeft / slideWidth);
+ setCurrentSlide(newSlide);
+ }
+ };
+
+ return (
+ <>
+ {
- imgSrc?: string | { light: string; dark: string };
+ imgSrc?: string;
minContentHeight?: number;
+ isRounded?: boolean;
+ aspectRatio?: string;
}
// @docusaurus/plugin-ideal-image transforms image imports into objects like
// { src: { src: "/img/file.hash.png" } } instead of plain URL strings.
// Extract the URL string from such objects.
function toUrl(value: unknown): string | undefined {
- if (typeof value === "string") return value;
- if (!value || typeof value !== "object") return undefined;
+ if (typeof value === "string") {
+ return value;
+ }
+ if (!value || typeof value !== "object") {
+ return undefined;
+ }
const { src } = value as Record;
- if (typeof src === "string") return src;
- if (src && typeof src === "object") return (src as Record).src as string;
+ if (typeof src === "string") {
+ return src;
+ }
+ if (src && typeof src === "object") {
+ return (src as Record).src as string;
+ }
return undefined;
}
@@ -26,9 +35,13 @@ export default function LazyImage({
className,
style,
minContentHeight = 100,
+ isRounded = true,
+ loading = "lazy",
+ aspectRatio,
...props
}: LazyImageProps) {
- const [isLoaded, setIsLoaded] = useState(false);
+ const isEager = loading === "eager";
+ const [isLoaded, setIsLoaded] = useState(isEager);
const imgRef = useRef(null);
// Check if image is already loaded after hydration
@@ -38,44 +51,40 @@ export default function LazyImage({
}
}, []);
- const sources = getSources({ imgSrc, src });
+ const imageSrc = src || toUrl(imgSrc);
+
+ if (!imageSrc) {
+ return null;
+ }
return (
- {!isLoaded && }
-
+ )}
+ 
setIsLoaded(true)}
onError={() => setIsLoaded(true)}
- loading="lazy"
+ loading={loading}
/>
);
}
-
-function getSources({ imgSrc, src }: Pick): ThemedImageProps["sources"] {
- if (src) {
- return { light: src, dark: src };
- }
-
- if (imgSrc && typeof imgSrc === "object" && "light" in imgSrc && "dark" in imgSrc) {
- return imgSrc;
- }
-
- const resolved = toUrl(imgSrc);
- if (resolved) {
- return { light: resolved, dark: resolved };
- }
-
- return imgSrc;
-}
diff --git a/src/components/Common/Toggle.tsx b/src/components/Common/Toggle.tsx
new file mode 100644
index 0000000000..ef157f86ca
--- /dev/null
+++ b/src/components/Common/Toggle.tsx
@@ -0,0 +1,35 @@
+import React from "react";
+import clsx from "clsx";
+
+interface ToggleOption {
+ value: T;
+ label: string;
+}
+
+interface ToggleProps {
+ options: ToggleOption[];
+ value: T;
+ onChange: (value: T) => void;
+ className?: string;
+}
+
+export default function Toggle({ options, value, onChange, className }: ToggleProps) {
+ return (
+
+
+
+
+ {title && (
+
+
+ )}
+
+ {title}
+
+ {headerAction}
+
+
+
+ {children}
+
+
+
+
+
+ {images.map((image, index) => (
+
+ {images.length > 1 && (
+
+
+ ))}
+
+ {images.map((_, index) => (
+
+ )}
+
+ {visibleImages[0] && (
+
+
+ {images.length > 3 && (
+ = 3 && "flex-[592]"
+ )}
+ >
+
+ )}
+ {visibleImages.length === 2 && visibleImages[1] && (
+
+
+ )}
+ {visibleImages.length >= 3 && (
+
+ {visibleImages[1] && (
+
+ )}
+
+
+ )}
+
+ {visibleImages[2] && (
+
+
+ )}
+
+ +{remainingCount}
+
+ )}
+
+ {images.slice(3).map((img, index) => (
+
+ )}
+
+ );
+}
diff --git a/src/components/Common/Icon.tsx b/src/components/Common/Icon.tsx
index c33e506cea..f989a8b997 100644
--- a/src/components/Common/Icon.tsx
+++ b/src/components/Common/Icon.tsx
@@ -2,7 +2,7 @@ import React from "react";
import { IconName } from "../../typescript/iconName";
import clsx from "clsx";
-export type IconSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+export type IconSize = "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export interface IconProps {
icon: IconName;
@@ -33,6 +33,8 @@ function getSvg(base64String: string, sizeClass: string): string {
function getSizeClass(size?: IconSize): `w-${number} h-${number}` {
switch (size) {
+ case "2xs":
+ return "w-3 h-3";
case "xs":
return "w-4 h-4";
case "sm":
diff --git a/src/components/Common/LazyImage.tsx b/src/components/Common/LazyImage.tsx
index e083d5d20d..c41ac6d8b8 100644
--- a/src/components/Common/LazyImage.tsx
+++ b/src/components/Common/LazyImage.tsx
@@ -1,21 +1,30 @@
import React, { useState, useEffect, useRef } from "react";
import clsx from "clsx";
-import ThemedImage, { Props as ThemedImageProps } from "@theme/ThemedImage";
export interface LazyImageProps extends React.ImgHTMLAttributes
+ {options.map((option) => (
+
+ ))}
+
+ );
+}
diff --git a/src/components/Guides/FeaturedGuides.tsx b/src/components/Guides/FeaturedGuides.tsx
index b1ac008ce2..fb6a603fbc 100644
--- a/src/components/Guides/FeaturedGuides.tsx
+++ b/src/components/Guides/FeaturedGuides.tsx
@@ -33,16 +33,15 @@ export default function FeaturedGuides({ guidesTitles }: FeaturedGuidesProps) {
Featured guides
- {featuredGuides.map((guide, index) => (
+ {featuredGuides.map((guide) => (
diff --git a/src/components/Guides/RecentGuides.tsx b/src/components/Guides/RecentGuides.tsx
index b079aefb23..1dda02d565 100644
--- a/src/components/Guides/RecentGuides.tsx
+++ b/src/components/Guides/RecentGuides.tsx
@@ -38,7 +38,7 @@ export default function RecentGuides() {
.filter((doc) => doc.id !== "home")
.map((doc: any) => ({
title: doc.title || doc.id,
- url: doc.externalUrl || doc.permalink,
+ url: doc.external_url || doc.permalink,
tags: doc.tags || [],
time: doc.lastUpdatedAt ? getRelativeTime(doc.lastUpdatedAt) : "Recently",
lastUpdatedAt: doc.lastUpdatedAt || 0,
diff --git a/src/components/IconGallery/IconGalleryCard.tsx b/src/components/IconGallery/IconGalleryCard.tsx
index 1939cdbacf..e95dae7dab 100644
--- a/src/components/IconGallery/IconGalleryCard.tsx
+++ b/src/components/IconGallery/IconGalleryCard.tsx
@@ -15,7 +15,6 @@ export default function IconGalleryCard({ iconName }: IconGalleryCardProps) {
setCopied(true);
window.setTimeout(() => setCopied(false), 2000);
} catch (err) {
- // eslint-disable-next-line no-console
console.error("Failed to copy icon name to clipboard:", err);
}
};
diff --git a/src/components/LanguageSwitcher.tsx b/src/components/LanguageSwitcher.tsx
index 3ac46a6b19..7fefef3f7a 100644
--- a/src/components/LanguageSwitcher.tsx
+++ b/src/components/LanguageSwitcher.tsx
@@ -1,21 +1,8 @@
import React, { useEffect } from "react";
import { useLanguage, type DocsLanguage } from "./LanguageStore";
+import { languageConfig } from "./languageConfig";
import clsx from "clsx";
-interface LanguageOption {
- label: string;
- value: DocsLanguage;
- brand: string;
-}
-
-const languageOptions: LanguageOption[] = [
- { label: "C#", value: "csharp", brand: "#9179E4" },
- { label: "Java", value: "java", brand: "#f89820" },
- { label: "Python", value: "python", brand: "#fbcb24" },
- { label: "PHP", value: "php", brand: "#8993be" },
- { label: "Node.js", value: "nodejs", brand: "#3c873a" },
-];
-
type LanguageSwitcherProps = {
supportedLanguages: DocsLanguage[];
flush?: boolean;
@@ -35,7 +22,7 @@ export default function LanguageSwitcher({ supportedLanguages, flush = false }:
return (
- {languageOptions
+ {languageConfig
.filter((lang) => supportedLanguages.includes(lang.value))
.map((lang) => {
const isActive = language === lang.value;
diff --git a/src/components/MarkdownImageLightbox.tsx b/src/components/MarkdownImageLightbox.tsx
index 7bbdcc1fa3..48d48a0de9 100644
--- a/src/components/MarkdownImageLightbox.tsx
+++ b/src/components/MarkdownImageLightbox.tsx
@@ -1,9 +1,11 @@
import React, { useEffect, useState } from "react";
+import { useLocation } from "@docusaurus/router";
import Lightbox from "yet-another-react-lightbox";
-import "yet-another-react-lightbox/styles.css";
import Captions from "yet-another-react-lightbox/plugins/captions";
-import { useLocation } from "@docusaurus/router";
-import { Share } from "yet-another-react-lightbox/plugins";
+import Download from "yet-another-react-lightbox/plugins/download";
+import Zoom from "yet-another-react-lightbox/plugins/zoom";
+import "yet-another-react-lightbox/styles.css";
+import "yet-another-react-lightbox/plugins/captions.css";
type Slide = { src: string; description?: string };
type CandidateElement = HTMLDivElement | HTMLImageElement;
@@ -132,11 +134,11 @@ export default function MarkdownImageLightbox() {
close={() => setOpen(false)}
index={currentIndex}
slides={slides}
- plugins={[Share, Captions]}
+ plugins={[Download, Captions, Zoom]}
captions={{
- descriptionTextAlign: "center",
+ descriptionTextAlign: "start",
descriptionMaxLines: 2,
- showToggle: false,
+ showToggle: true,
}}
/>
);
diff --git a/src/components/Samples/Hub/Partials/FilterCategory.tsx b/src/components/Samples/Hub/Partials/FilterCategory.tsx
new file mode 100644
index 0000000000..f586431b35
--- /dev/null
+++ b/src/components/Samples/Hub/Partials/FilterCategory.tsx
@@ -0,0 +1,114 @@
+import React, { useEffect } from "react";
+import { motion, AnimatePresence } from "motion/react";
+import { Icon } from "@site/src/components/Common/Icon";
+import Checkbox from "@site/src/components/Common/Checkbox";
+import useBoolean from "@site/src/hooks/useBoolean";
+
+interface FilterTag {
+ key: string;
+ label: string;
+}
+
+interface FilterCategoryProps {
+ name: string;
+ label: string;
+ tags: FilterTag[];
+ selectedTags: Set;
+ onTagToggle: (tagKey: string) => void;
+ isExpanded: boolean;
+ onToggleExpanded: () => void;
+}
+
+export default function FilterCategory({
+ label,
+ tags,
+ selectedTags,
+ onTagToggle,
+ isExpanded,
+ onToggleExpanded,
+}: FilterCategoryProps) {
+ const { value: isTagsExpanded, setTrue: expandTags, setFalse: collapseTags } = useBoolean(false);
+ const [manuallyCollapsed, setManuallyCollapsed] = React.useState(false);
+
+ const visibleTags = isTagsExpanded ? tags : tags.slice(0, 5);
+ const hiddenCount = Math.max(0, tags.length - 5);
+
+ useEffect(() => {
+ if (!isTagsExpanded && !manuallyCollapsed && tags.length > 5) {
+ const hiddenTags = tags.slice(5);
+ const hasSelectedHiddenTag = hiddenTags.some((tag) => selectedTags.has(tag.key));
+ if (hasSelectedHiddenTag) {
+ expandTags();
+ }
+ }
+ }, [selectedTags, tags, isTagsExpanded, expandTags, manuallyCollapsed]);
+
+ const handleToggleTagsExpanded = () => {
+ if (isTagsExpanded) {
+ setManuallyCollapsed(true);
+ collapseTags();
+ } else {
+ setManuallyCollapsed(false);
+ expandTags();
+ }
+ };
+
+ return (
+
+ {languageKey}
+
+ );
+ }
+
+ return (
+
+ {config.label}
+
+ );
+}
diff --git a/src/components/Samples/Hub/Partials/SampleCard.tsx b/src/components/Samples/Hub/Partials/SampleCard.tsx
new file mode 100644
index 0000000000..62ab8252bf
--- /dev/null
+++ b/src/components/Samples/Hub/Partials/SampleCard.tsx
@@ -0,0 +1,166 @@
+import React, { ReactNode } from "react";
+import Link from "@docusaurus/Link";
+import Heading from "@theme/Heading";
+import LazyImage from "@site/src/components/Common/LazyImage";
+import clsx from "clsx";
+import Tag from "@site/src/theme/Tag";
+import LanguageTag from "@site/src/components/Samples/Hub/Partials/LanguageTag";
+
+interface TagWithCategory {
+ label: string;
+ key: string;
+ category?: string;
+}
+
+export interface SampleCardProps {
+ title: string;
+ description: ReactNode;
+ imgSrc?: string;
+ imgAlt?: string;
+ imgWidth?: number;
+ imgHeight?: number;
+ url: string;
+ tags?: TagWithCategory[];
+ onTagClick?: (tagKey: string) => void;
+ selectedTags?: Set;
+}
+
+export default function SampleCard({
+ title,
+ description,
+ imgSrc,
+ imgAlt = "",
+ url,
+ tags = [],
+ onTagClick,
+ selectedTags,
+}: SampleCardProps) {
+ const hasImage = Boolean(imgSrc);
+
+ const challengesSolutionsTags = tags.filter((t) => t.category === "challenges-solutions");
+ const featureTags = tags.filter((t) => t.category === "feature");
+ const techStackTags = tags.filter((t) => t.category === "tech-stack");
+
+ const languageTags = techStackTags.filter((t) => ["csharp", "java", "python", "php", "nodejs"].includes(t.key));
+
+ const handleTagClick = (e: React.MouseEvent, tag: TagWithCategory) => {
+ e.preventDefault();
+ e.stopPropagation();
+ onTagClick?.(tag.key);
+ };
+
+ const isTagSelected = (tag: TagWithCategory) => {
+ if (!selectedTags || selectedTags.size === 0) {
+ return true;
+ }
+ return selectedTags.has(tag.key);
+ };
+
+ return (
+ ;
+ onTagToggle: (tagKey: string) => void;
+ matchLogic: "any" | "all";
+ onMatchLogicChange: (logic: "any" | "all") => void;
+ onClearFilters?: () => void;
+ showHeader?: boolean;
+}
+
+export default function SamplesFilter({
+ categories,
+ selectedTags,
+ onTagToggle,
+ matchLogic,
+ onMatchLogicChange,
+ onClearFilters,
+ showHeader = true,
+}: SamplesFilterProps) {
+ const [expandedCategories, setExpandedCategories] = useState>(new Set(categories.map((c) => c.name)));
+ const [manuallyCollapsed, setManuallyCollapsed] = useState>(new Set());
+ const [searchQuery, setSearchQuery] = useState("");
+
+ useEffect(() => {
+ const categoriesToExpand = new Set(expandedCategories);
+ let hasChanges = false;
+
+ categories.forEach((category) => {
+ const hasSelectedTag = category.tags.some((tag) => selectedTags.has(tag.key));
+ if (hasSelectedTag && !categoriesToExpand.has(category.name) && !manuallyCollapsed.has(category.name)) {
+ categoriesToExpand.add(category.name);
+ hasChanges = true;
+ }
+ });
+
+ if (hasChanges) {
+ setExpandedCategories(categoriesToExpand);
+ }
+ }, [selectedTags, categories, manuallyCollapsed, expandedCategories]);
+
+ const toggleCategory = (categoryName: string) => {
+ const newExpanded = new Set(expandedCategories);
+ const newManuallyCollapsed = new Set(manuallyCollapsed);
+
+ if (newExpanded.has(categoryName)) {
+ newExpanded.delete(categoryName);
+ newManuallyCollapsed.add(categoryName);
+ } else {
+ newExpanded.add(categoryName);
+ newManuallyCollapsed.delete(categoryName);
+ }
+ setExpandedCategories(newExpanded);
+ setManuallyCollapsed(newManuallyCollapsed);
+ };
+
+ const filteredCategories = categories
+ .map((category) => ({
+ ...category,
+ tags: category.tags.filter((tag) => tag.label.toLowerCase().includes(searchQuery.toLowerCase())),
+ }))
+ .filter((category) => category.tags.length > 0);
+
+ const handleClearAll = () => {
+ setSearchQuery("");
+ onMatchLogicChange("any");
+ onClearFilters?.();
+ };
+
+ const hasActiveFilters = selectedTags.size > 0 || searchQuery.length > 0 || matchLogic !== "any";
+
+ return (
+ ;
+ matchLogic: "any" | "all";
+ onTagClick?: (tagKey: string) => void;
+}
+
+export default function SamplesGrid({ samples, selectedTags, matchLogic, onTagClick }: SamplesGridProps) {
+ const filteredSamples = useMemo(() => {
+ if (selectedTags.size === 0) {
+ return samples;
+ }
+
+ return samples.filter((sample) => {
+ const sampleTagKeys = new Set(sample.tags.map((t) => t.key));
+
+ if (matchLogic === "any") {
+ return Array.from(selectedTags).some((tag) => sampleTagKeys.has(tag));
+ } else {
+ return Array.from(selectedTags).every((tag) => sampleTagKeys.has(tag));
+ }
+ });
+ }, [samples, selectedTags, matchLogic]);
+
+ if (filteredSamples.length === 0) {
+ return (
+ = {
+ "tech-stack": "Tech Stack",
+ "challenges-solutions": "Challenges & Solutions",
+ feature: "Features",
+ other: "Other",
+};
+
+export default function SamplesHomePage() {
+ const pluginData = usePluginData("recent-samples-plugin") as PluginData | undefined;
+ const history = useHistory();
+ const location = useLocation();
+
+ const [selectedTags, setSelectedTags] = useState>(() => {
+ const params = new URLSearchParams(location.search);
+ const tagsParam = params.get("tags");
+ return tagsParam ? new Set(tagsParam.split(",")) : new Set();
+ });
+
+ const [matchLogic, setMatchLogic] = useState<"any" | "all">(() => {
+ const params = new URLSearchParams(location.search);
+ const logicParam = params.get("match");
+ return logicParam === "all" ? "all" : "any";
+ });
+
+ const samples = pluginData?.samples || [];
+ const allTags = pluginData?.tags || [];
+
+ const categories = useMemo(() => {
+ const categoryMap: Record = {};
+
+ allTags.forEach((tag) => {
+ const category = tag.category || "other";
+ if (!categoryMap[category]) {
+ categoryMap[category] = {
+ name: category,
+ label: categoryLabels[category] || "Other",
+ tags: [],
+ };
+ }
+ categoryMap[category].tags.push({
+ key: tag.key,
+ label: tag.label,
+ count: tag.count,
+ });
+ });
+
+ return Object.values(categoryMap);
+ }, [allTags]);
+
+ useEffect(() => {
+ const params = new URLSearchParams();
+
+ if (selectedTags.size > 0) {
+ params.set("tags", Array.from(selectedTags).join(","));
+ }
+
+ if (matchLogic !== "any") {
+ params.set("match", matchLogic);
+ }
+
+ const newSearch = params.toString();
+ const currentSearch = location.search.replace(/^\?/, "");
+
+ if (newSearch !== currentSearch) {
+ history.replace({
+ pathname: location.pathname,
+ search: newSearch ? `?${newSearch}` : "",
+ });
+ }
+ }, [selectedTags, matchLogic, history, location.pathname, location.search]);
+
+ const handleTagToggle = (tagKey: string) => {
+ const newSelected = new Set(selectedTags);
+ if (newSelected.has(tagKey)) {
+ newSelected.delete(tagKey);
+ } else {
+ newSelected.add(tagKey);
+ }
+ setSelectedTags(newSelected);
+ };
+
+ const { value: isFilterDrawerOpen, setTrue: openFilterDrawer, setFalse: closeFilterDrawer } = useBoolean(false);
+
+ const hasActiveFilters = selectedTags.size > 0 || matchLogic !== "any";
+
+ const { siteConfig } = useDocusaurusContext();
+ const siteUrl = siteConfig.url;
+ const samplesUrl = `${siteUrl}/samples`;
+
+ const filteredSamples = samples.filter((s) => s.id !== "home");
+
+ const collectionPageJsonLd = JSON.stringify({
+ "@context": "https://schema.org",
+ "@type": "CollectionPage",
+ "@id": samplesUrl,
+ name: "RavenDB Code Samples",
+ description: "Production-ready code samples, architecture patterns, and starter kits built with RavenDB.",
+ url: samplesUrl,
+ isPartOf: { "@type": "WebSite", "@id": `${siteUrl}/` },
+ breadcrumb: {
+ "@type": "BreadcrumbList",
+ itemListElement: [
+ {
+ "@type": "ListItem",
+ position: 1,
+ name: "RavenDB Documentation",
+ item: `${siteUrl}/`,
+ },
+ {
+ "@type": "ListItem",
+ position: 2,
+ name: "Samples",
+ item: samplesUrl,
+ },
+ ],
+ },
+ mainEntity: {
+ "@type": "ItemList",
+ name: "RavenDB Code Samples",
+ numberOfItems: filteredSamples.length,
+ itemListElement: filteredSamples.map((sample, index) => ({
+ "@type": "ListItem",
+ position: index + 1,
+ url: `${siteUrl}${sample.permalink}`,
+ name: sample.title,
+ ...(sample.description ? { description: sample.description } : {}),
+ })),
+ },
+ });
+
+ return (
+ <>
+
+
+
+ = {
+ guide: {
+ title: "Guide",
+ icon: "guides",
+ },
+ documentation: {
+ title: "Documentation",
+ icon: "database",
+ },
+ video: {
+ title: "Video Walkthrough",
+ icon: "play",
+ },
+};
+
+export default function RelatedResource({
+ className,
+ type,
+ documentationType = "docs",
+ subtitle,
+ articleKey,
+ externalUrl,
+}: RelatedResourceProps) {
+ const latestVersion = useLatestVersion() as string;
+ const config = TYPE_CONFIG[type];
+
+ const url = React.useMemo(() => {
+ if (externalUrl) {
+ return externalUrl;
+ }
+
+ if (type === "guide") {
+ return `/guides/${articleKey}`;
+ }
+
+ const basePath = documentationType === "cloud" ? "/cloud" : `/${latestVersion}`;
+ return `${basePath}/${articleKey}`;
+ }, [type, documentationType, articleKey, externalUrl, latestVersion]);
+
+ const icon = type === "documentation" && documentationType === "cloud" ? "cloud" : config.icon;
+
+ return (
+
+
) : (
+
+
+
+ {isExpanded && (
+
+
+ )}
+
+
+ );
+}
diff --git a/src/components/Samples/Hub/Partials/LanguageTag.tsx b/src/components/Samples/Hub/Partials/LanguageTag.tsx
new file mode 100644
index 0000000000..409ffa5f5c
--- /dev/null
+++ b/src/components/Samples/Hub/Partials/LanguageTag.tsx
@@ -0,0 +1,36 @@
+import React from "react";
+import Tag from "@site/src/theme/Tag";
+import { getLanguageConfig } from "../../../languageConfig";
+
+export interface LanguageTagProps {
+ languageKey: string;
+ className?: string;
+ onClick?: (e: React.MouseEvent) => void;
+}
+
+export default function LanguageTag({ languageKey, className, onClick }: LanguageTagProps) {
+ const config = getLanguageConfig(languageKey);
+
+ if (!config) {
+ return (
+
+ {visibleTags.map((tag) => (
+ onTagToggle(tag.key)}
+ label={tag.label}
+ />
+ ))}
+
+ {hiddenCount > 0 && (
+
+ )}
+
+
+
+
+
+
+ );
+}
diff --git a/src/components/Samples/Hub/Partials/SamplesDecoration.tsx b/src/components/Samples/Hub/Partials/SamplesDecoration.tsx
new file mode 100644
index 0000000000..a17bb052ca
--- /dev/null
+++ b/src/components/Samples/Hub/Partials/SamplesDecoration.tsx
@@ -0,0 +1,547 @@
+import { useState, useEffect } from "react";
+
+const defaultColors = {
+ lightest: "#86BAF2",
+ darkest: "#2382E7",
+ lighter: "#5FA4ED",
+};
+
+export default function SamplesDecoration() {
+ const [colors, setColors] = useState(defaultColors);
+
+ useEffect(() => {
+ const getColorValue = (varName: string, fallback: string): string => {
+ const value = getComputedStyle(document.documentElement).getPropertyValue(varName).trim();
+ return value || fallback;
+ };
+
+ const updateColors = () => {
+ setColors({
+ lightest: getColorValue("--ifm-color-primary-lightest", defaultColors.lightest),
+ darkest: getColorValue("--ifm-color-primary-darkest", defaultColors.darkest),
+ lighter: getColorValue("--ifm-color-primary-lighter", defaultColors.lighter),
+ });
+ };
+
+ updateColors();
+
+ const observer = new MutationObserver(updateColors);
+ observer.observe(document.documentElement, {
+ attributes: true,
+ attributeFilter: ["data-theme"],
+ });
+
+ return () => observer.disconnect();
+ }, []);
+
+ return (
+
+ );
+}
diff --git a/src/components/Samples/Hub/Partials/SamplesFilter.tsx b/src/components/Samples/Hub/Partials/SamplesFilter.tsx
new file mode 100644
index 0000000000..a9c3ad66cf
--- /dev/null
+++ b/src/components/Samples/Hub/Partials/SamplesFilter.tsx
@@ -0,0 +1,150 @@
+import React, { useState, useEffect } from "react";
+import Heading from "@theme/Heading";
+import clsx from "clsx";
+import Toggle from "@site/src/components/Common/Toggle";
+import FilterCategory from "./FilterCategory";
+import Button from "@site/src/components/Common/Button";
+
+interface FilterTag {
+ key: string;
+ label: string;
+}
+
+interface FilterCategoryData {
+ name: string;
+ label: string;
+ tags: FilterTag[];
+}
+
+interface SamplesFilterProps {
+ categories: FilterCategoryData[];
+ selectedTags: Set
+ {hasImage && (
+ <>
+
+
+ {languageTags.map((tag) => (
+ handleTagClick(e, tag) : undefined}
+ className={clsx(!isTagSelected(tag) && "opacity-50")}
+ />
+ ))}
+
+ )}
+
+ )}
+
+
+
+
+ {title}
+
+
+
+ {description}
+ +
+ {challengesSolutionsTags.length > 0 && (
+
+
+ Challenges & Solutions
+
+ )}
+
+ {featureTags.length > 0 && (
+
+ {challengesSolutionsTags.map((tag) => (
+ handleTagClick(e, tag) : undefined}
+ className={clsx(
+ onTagClick && "cursor-pointer",
+ !isTagSelected(tag) && "opacity-50"
+ )}
+ >
+ {tag.label}
+
+ ))}
+
+
+ Features
+
+ )}
+
+ {featureTags.map((tag) => (
+ handleTagClick(e, tag) : undefined}
+ className={clsx(
+ onTagClick && "cursor-pointer",
+ !isTagSelected(tag) && "opacity-50"
+ )}
+ >
+ {tag.label}
+
+ ))}
+
+
+ {showHeader && (
+ toggleCategory(category.name)}
+ />
+ ))
+ ) : (
+
+ );
+}
diff --git a/src/components/Samples/Hub/Partials/SamplesGrid.tsx b/src/components/Samples/Hub/Partials/SamplesGrid.tsx
new file mode 100644
index 0000000000..ece052a973
--- /dev/null
+++ b/src/components/Samples/Hub/Partials/SamplesGrid.tsx
@@ -0,0 +1,73 @@
+import React, { useMemo } from "react";
+import clsx from "clsx";
+import { SampleCard } from "@site/src/components/Samples";
+import Heading from "@theme/Heading";
+import type { Sample } from "../../types";
+
+interface SamplesGridProps {
+ samples: Sample[];
+ selectedTags: Set
+
+ Filters
+
+ {hasActiveFilters && (
+
+ )}
+
+ )}
+
+ setSearchQuery(e.target.value)}
+ className={clsx(
+ "px-3 py-2 rounded-full",
+ "border border-black/10 dark:border-white/10",
+ "text-sm text-black dark:text-white",
+ "placeholder-black/30 dark:placeholder-white/30"
+ )}
+ />
+
+
+
+
+ Match logic
+
+
+
+ {filteredCategories.length > 0 ? (
+ filteredCategories.map((category) => (
+ Nothing found
+ )}
+
+
+ );
+ }
+
+ return (
+ No samples found matching your filters.
+
+
+ );
+}
diff --git a/src/components/Samples/Hub/Partials/SamplesHeader.tsx b/src/components/Samples/Hub/Partials/SamplesHeader.tsx
new file mode 100644
index 0000000000..cbe3fa2452
--- /dev/null
+++ b/src/components/Samples/Hub/Partials/SamplesHeader.tsx
@@ -0,0 +1,26 @@
+import React from "react";
+import Heading from "@theme/Heading";
+import clsx from "clsx";
+import SamplesDecoration from "./SamplesDecoration";
+
+export default function SamplesHeader() {
+ return (
+
+
+ Samples
+
+
+ {filteredSamples.length}
+
+
+
+ {filteredSamples.map((sample) => (
+
+
+
+ );
+}
diff --git a/src/components/Samples/Hub/SamplesHomePage.tsx b/src/components/Samples/Hub/SamplesHomePage.tsx
new file mode 100644
index 0000000000..276e2adc60
--- /dev/null
+++ b/src/components/Samples/Hub/SamplesHomePage.tsx
@@ -0,0 +1,219 @@
+import React, { useState, useMemo, useEffect } from "react";
+import { SamplesHeader, SamplesFilter, SamplesGrid } from "@site/src/components/Samples";
+import { usePluginData } from "@docusaurus/useGlobalData";
+import { useHistory, useLocation } from "@docusaurus/router";
+import Head from "@docusaurus/Head";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import type { Tag, PluginData } from "../types";
+import Drawer from "@site/src/components/Common/Drawer";
+import useBoolean from "@site/src/hooks/useBoolean";
+import Button from "@site/src/components/Common/Button";
+import clsx from "clsx";
+
+const categoryLabels: Record
+
+ Explore Samples
+
+
+ Production-ready code samples, architecture patterns, and starter kits.
+
+
+
+
+
+ {
+ setSelectedTags(new Set());
+ setMatchLogic("any");
+ }}
+ variant="secondary"
+ size="xs"
+ >
+ Clear all
+
+ )
+ }
+ >
+
+
+
+
+ );
+}
diff --git a/src/components/Samples/Overview/Partials/ActionsCard.tsx b/src/components/Samples/Overview/Partials/ActionsCard.tsx
new file mode 100644
index 0000000000..3860d5ce6f
--- /dev/null
+++ b/src/components/Samples/Overview/Partials/ActionsCard.tsx
@@ -0,0 +1,36 @@
+import React from "react";
+import clsx from "clsx";
+import Button from "@site/src/components/Common/Button";
+
+export interface ActionsCardProps {
+ className?: string;
+ githubUrl?: string;
+ demoUrl?: string;
+}
+
+export default function ActionsCard({ className, githubUrl, demoUrl }: ActionsCardProps) {
+ return (
+
+ setSelectedTags(new Set())}
+ />
+
+
+
+ setSelectedTags(new Set())}
+ showHeader={false}
+ />
+
+
+
+
+
+
+ );
+}
diff --git a/src/components/Samples/Overview/Partials/FeatureAccordion.tsx b/src/components/Samples/Overview/Partials/FeatureAccordion.tsx
new file mode 100644
index 0000000000..e69423583a
--- /dev/null
+++ b/src/components/Samples/Overview/Partials/FeatureAccordion.tsx
@@ -0,0 +1,78 @@
+import React, { ReactNode } from "react";
+import clsx from "clsx";
+import { motion } from "motion/react";
+import { Icon } from "@site/src/components/Common/Icon";
+import { IconName } from "@site/src/typescript/iconName";
+import useBoolean from "@site/src/hooks/useBoolean";
+
+export interface FeatureAccordionProps {
+ className?: string;
+ title: string;
+ description: string;
+ icon?: IconName;
+ children?: ReactNode;
+ defaultExpanded?: boolean;
+}
+
+export default function FeatureAccordion({
+ className,
+ title,
+ description,
+ icon = "link",
+ children,
+ defaultExpanded = false,
+}: FeatureAccordionProps) {
+ const { value: isExpanded, toggle } = useBoolean(defaultExpanded);
+
+ return (
+
+ {githubUrl && (
+
+ )}
+ {demoUrl && (
+
+ )}
+
+
+
+ {children && (
+
+ );
+}
diff --git a/src/components/Samples/Overview/Partials/RelatedResource.tsx b/src/components/Samples/Overview/Partials/RelatedResource.tsx
new file mode 100644
index 0000000000..5d8d51d9dc
--- /dev/null
+++ b/src/components/Samples/Overview/Partials/RelatedResource.tsx
@@ -0,0 +1,94 @@
+import React from "react";
+import clsx from "clsx";
+import { Icon } from "@site/src/components/Common/Icon";
+import { IconName } from "@site/src/typescript/iconName";
+import Link from "@docusaurus/Link";
+import { useLatestVersion } from "@site/src/hooks/useLatestVersion";
+
+type ResourceType = "guide" | "documentation" | "video";
+
+type DocumentationType = "docs" | "cloud";
+
+export interface RelatedResourceProps {
+ className?: string;
+ type: ResourceType;
+ documentationType?: DocumentationType;
+ subtitle: string;
+ articleKey?: string;
+ externalUrl?: string;
+}
+
+const TYPE_CONFIG: Record
+
+ )}
+
+
+
+ {children}
+
+
+
+
+
+
+ );
+}
diff --git a/src/components/Samples/Overview/Partials/SampleMetadataColumn.tsx b/src/components/Samples/Overview/Partials/SampleMetadataColumn.tsx
new file mode 100644
index 0000000000..46e6cfd1bd
--- /dev/null
+++ b/src/components/Samples/Overview/Partials/SampleMetadataColumn.tsx
@@ -0,0 +1,160 @@
+import React, { useMemo } from "react";
+import { useDoc } from "@docusaurus/plugin-content-docs/client";
+import { usePluginData } from "@docusaurus/useGlobalData";
+import clsx from "clsx";
+import Heading from "@theme/Heading";
+import Tag from "@site/src/theme/Tag";
+import type { PluginData } from "@site/src/components/Samples/types";
+import ActionsCard from "./ActionsCard";
+import RelatedResource from "./RelatedResource";
+
+export interface SampleMetadataColumnProps {
+ className?: string;
+}
+
+interface TagData {
+ [key: string]: {
+ label: string;
+ };
+}
+
+function createFilterUrl(tagKey: string): string {
+ return `/samples?tags=${tagKey}`;
+}
+
+function getTagsWithLabels(tagKeys: string[] | undefined, tagData: TagData) {
+ if (!tagKeys || tagKeys.length === 0) {
+ return [];
+ }
+
+ return tagKeys.map((key) => ({
+ key,
+ label: tagData[key]?.label || key,
+ }));
+}
+
+interface TagSectionProps {
+ title: string;
+ tags: Array<{ key: string; label: string }>;
+}
+
+function TagSection({ title, tags }: TagSectionProps) {
+ if (tags.length === 0) {
+ return null;
+ }
+
+ return (
+ + {config.title} +
++ {subtitle} +
+
+
+ {title}
+
+
+ );
+}
+
+export default function SampleMetadataColumn({ className }: SampleMetadataColumnProps) {
+ const { frontMatter } = useDoc();
+ const pluginData = usePluginData("recent-samples-plugin") as PluginData | undefined;
+
+ const { challengesSolutionsTagsData, featureTagsData, techStackTagsData } = useMemo(() => {
+ const allTags = pluginData?.tags || [];
+
+ const challengesSolutionsTags: TagData = {};
+ const featureTags: TagData = {};
+ const techStackTags: TagData = {};
+
+ allTags.forEach((tag) => {
+ const tagEntry = { label: tag.label };
+ if (tag.category === "challenges-solutions") {
+ challengesSolutionsTags[tag.key] = tagEntry;
+ } else if (tag.category === "feature") {
+ featureTags[tag.key] = tagEntry;
+ } else if (tag.category === "tech-stack") {
+ techStackTags[tag.key] = tagEntry;
+ }
+ });
+
+ return {
+ challengesSolutionsTagsData: challengesSolutionsTags,
+ featureTagsData: featureTags,
+ techStackTagsData: techStackTags,
+ };
+ }, [pluginData]);
+
+ const challengesSolutionsTagKeys = frontMatter.challenges_solutions_tags;
+ const featureTagKeys = frontMatter.feature_tags;
+ const techStackTagKeys = frontMatter.tech_stack_tags;
+ const category = frontMatter.category;
+ const license = frontMatter.license;
+ const licenseUrl = frontMatter.license_url;
+ const repositoryUrl = frontMatter.repository_url;
+ const demoUrl = frontMatter.demo_url;
+ const relatedResourceItems = frontMatter.related_resources;
+
+ const challengesSolutionsTags = getTagsWithLabels(challengesSolutionsTagKeys, challengesSolutionsTagsData);
+ const featureTags = getTagsWithLabels(featureTagKeys, featureTagsData);
+ const techStackTags = getTagsWithLabels(techStackTagKeys, techStackTagsData);
+
+ return (
+
+ {tags.map((tag) => (
+
+ {tag.label}
+
+ ))}
+
+
+ {(repositoryUrl || demoUrl) &&
+ );
+}
diff --git a/src/components/Samples/Overview/SampleLayout.tsx b/src/components/Samples/Overview/SampleLayout.tsx
new file mode 100644
index 0000000000..5801fe01da
--- /dev/null
+++ b/src/components/Samples/Overview/SampleLayout.tsx
@@ -0,0 +1,26 @@
+import React, { ReactNode } from "react";
+import SampleMetadataColumn from "./Partials/SampleMetadataColumn";
+import Gallery from "@site/src/components/Common/Gallery";
+import { useDoc } from "@docusaurus/plugin-content-docs/client";
+
+interface SampleLayoutProps {
+ children: ReactNode;
+}
+
+export default function SampleLayout({ children }: SampleLayoutProps) {
+ const { frontMatter } = useDoc();
+ const gallery = frontMatter.gallery?.length ?
+
+ Category
+
+
+ )}
+
+ {license && (
+ {category}
+
+
+ License
+
+
+ )}
+
+ {relatedResourceItems && relatedResourceItems.length > 0 && (
+ + {licenseUrl ? ( + + {license} + + ) : ( + license + )} +
+
+
+ Related Resources
+
+
+ )}
+
+ {relatedResourceItems.map((resource, index) => (
+
+
+
+ );
+}
diff --git a/src/components/Samples/index.ts b/src/components/Samples/index.ts
new file mode 100644
index 0000000000..10837552e1
--- /dev/null
+++ b/src/components/Samples/index.ts
@@ -0,0 +1,15 @@
+// Sample overview page components
+export { default as ActionsCard } from "./Overview/Partials/ActionsCard";
+export { default as RelatedResource } from "./Overview/Partials/RelatedResource";
+export { default as FeatureAccordion } from "./Overview/Partials/FeatureAccordion";
+export { default as SampleMetadataColumn } from "./Overview/Partials/SampleMetadataColumn";
+export { default as SampleLayout } from "./Overview/SampleLayout";
+
+// Samples hub components
+export { default as SampleCard } from "./Hub/Partials/SampleCard";
+export { default as SamplesGrid } from "./Hub/Partials/SamplesGrid";
+export { default as SamplesFilter } from "./Hub/Partials/SamplesFilter";
+export { default as FilterCategory } from "./Hub/Partials/FilterCategory";
+export { default as SamplesHeader } from "./Hub/Partials/SamplesHeader";
+export { default as SamplesDecoration } from "./Hub/Partials/SamplesDecoration";
+export { default as SamplesHomePage } from "./Hub/SamplesHomePage";
diff --git a/src/components/Samples/types.ts b/src/components/Samples/types.ts
new file mode 100644
index 0000000000..a49af9fc8b
--- /dev/null
+++ b/src/components/Samples/types.ts
@@ -0,0 +1,21 @@
+export interface Tag {
+ key: string;
+ label: string;
+ category?: string;
+ count?: number;
+}
+
+export interface Sample {
+ id: string;
+ title: string;
+ description?: string;
+ permalink: string;
+ image?: string;
+ img_alt?: string;
+ tags: Array<{ label: string; key: string; category?: string }>;
+}
+
+export interface PluginData {
+ samples: Sample[];
+ tags: Tag[];
+}
diff --git a/src/components/languageConfig.ts b/src/components/languageConfig.ts
new file mode 100644
index 0000000000..96b08f23d2
--- /dev/null
+++ b/src/components/languageConfig.ts
@@ -0,0 +1,23 @@
+import type { DocsLanguage } from "./LanguageStore";
+
+export interface LanguageConfig {
+ label: string;
+ value: DocsLanguage;
+ brand: string;
+}
+
+export const languageConfig: LanguageConfig[] = [
+ { label: "C#", value: "csharp", brand: "#9179E4" },
+ { label: "Java", value: "java", brand: "#f89820" },
+ { label: "Python", value: "python", brand: "#fbcb24" },
+ { label: "PHP", value: "php", brand: "#8993be" },
+ { label: "Node.js", value: "nodejs", brand: "#3c873a" },
+];
+
+export function getLanguageConfig(languageKey: string): LanguageConfig | undefined {
+ return languageConfig.find((lang) => lang.value === languageKey);
+}
+
+export function getLanguageBrandColor(languageKey: string): string | undefined {
+ return getLanguageConfig(languageKey)?.brand;
+}
diff --git a/src/css/custom.css b/src/css/custom.css
index 4b558a679a..a0e77991b2 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -10,29 +10,18 @@
}
}
-/* Custom animations for layout switcher */
-@keyframes slide-in-from-bottom {
- from {
- opacity: 0;
- transform: translateY(16px);
- }
- to {
- opacity: 1;
- transform: translateY(0);
- }
+/* Prevent body scroll when drawer is open */
+body:has([data-drawer-open="true"]) {
+ overflow: hidden;
}
-@keyframes slide-in-from-left {
- from {
- opacity: 0;
- transform: translateX(-16px);
- }
- to {
- opacity: 1;
- transform: translateX(0);
- }
+/* Hide TOC column for sample pages */
+.plugin-id-samples .col.col--3 {
+ display: none !important;
}
+/* Custom animations for layout switcher */
+
@keyframes fade-in {
from {
opacity: 0;
@@ -48,14 +37,7 @@
.fade-in {
animation-name: fade-in;
-}
-
-.slide-in-from-bottom-4 {
- animation-name: slide-in-from-bottom;
-}
-
-.slide-in-from-left-4 {
- animation-name: slide-in-from-left;
+ animation-duration: 400ms;
}
/* Custom selection */
@@ -252,16 +234,6 @@ pre[class*="language-"] {
display: none;
}
-/* Custom styling for lightbox */
-.yarl__flex_center {
- @apply !p-[64px];
- flex-direction: column;
-}
-
-.yarl__slide_description_container {
- @apply mt-4 text-white;
-}
-
/* Custom border for alerts */
.alert {
@apply border;
@@ -381,7 +353,7 @@ a.breadcrumbs__link:hover {
}
/* Custom border-radius for document images */
-.theme-doc-markdown img {
+.plugin-id-default .theme-doc-markdown img {
@apply rounded-md;
}
@@ -570,10 +542,12 @@ hr {
@apply !mt-8;
}
-/* Home Page full width override */
-.guides-home-page [class*="docItemCol"],
-.cloud-home-page [class*="docItemCol"],
-.docs-home-page [class*="docItemCol"] {
+/* Full width override */
+.guidesHomePage [class*="docItemCol"],
+.cloudHomePage [class*="docItemCol"],
+.docsHomePage [class*="docItemCol"],
+.samplesHomePage [class*="docItemCol"],
+.plugin-id-samples [class*="docItemCol"] {
max-width: 100% !important;
}
@@ -627,6 +601,16 @@ a {
animation: skeleton-loading 2000ms infinite linear;
}
+/* Hide scrollbar utility */
+.scrollbar-none {
+ scrollbar-width: none;
+ -ms-overflow-style: none;
+}
+
+.scrollbar-none::-webkit-scrollbar {
+ display: none;
+}
+
[data-theme="dark"] .skeleton {
background-image: linear-gradient(
45deg,
@@ -689,7 +673,8 @@ a {
/* Disable navigation for Docs */
.plugin-id-default .pagination-nav,
-.plugin-id-cloud .pagination-nav {
+.plugin-id-cloud .pagination-nav,
+.plugin-id-samples .pagination-nav {
display: none;
}
@@ -756,3 +741,8 @@ a {
font-size: 0.75rem;
line-height: 1.2;
}
+
+/* Hide TOC for Samples */
+.plugin-id-samples [class*="tocCollapsibleButton"] {
+ display: none;
+}
diff --git a/src/hooks/useBoolean.ts b/src/hooks/useBoolean.ts
new file mode 100644
index 0000000000..7ecfd51a9a
--- /dev/null
+++ b/src/hooks/useBoolean.ts
@@ -0,0 +1,14 @@
+import { useCallback, useState } from "react";
+
+const useBoolean = (initial: boolean) => {
+ const [value, setValue] = useState(initial);
+ return {
+ value,
+ setValue,
+ toggle: useCallback(() => setValue((value: boolean) => !value), []),
+ setTrue: useCallback(() => setValue(true), []),
+ setFalse: useCallback(() => setValue(false), []),
+ };
+};
+
+export default useBoolean;
diff --git a/src/pages/guides/all.tsx b/src/pages/guides/all.tsx
index 58af25a19b..126aa9da58 100644
--- a/src/pages/guides/all.tsx
+++ b/src/pages/guides/all.tsx
@@ -72,7 +72,7 @@ function AllGuidesPageContent(): ReactNode {
"animate-in fade-in"
)}
>
- {sortedGuides.map((guide, index) => {
+ {sortedGuides.map((guide) => {
const formattedDate = guide.lastUpdatedAt
? new Date(guide.lastUpdatedAt * 1000).toLocaleDateString("en-US", {
month: "short",
@@ -85,19 +85,18 @@ function AllGuidesPageContent(): ReactNode {
key={guide.id}
title={guide.title}
description={guide.description}
- url={guide.externalUrl || guide.permalink}
+ url={guide.external_url || guide.permalink}
imgSrc={guide.image}
imgIcon={guide.icon}
tags={guide.tags}
date={formattedDate}
- animationDelay={index * 50}
/>
);
})}
+
+ {gallery}
+ {children}
+
+
+ {gallery}
+
- {sortedGuides.map((guide, index) => {
+ {sortedGuides.map((guide) => {
const formattedDate = guide.lastUpdatedAt
? new Date(guide.lastUpdatedAt * 1000).toLocaleDateString("en-US", {
month: "short",
@@ -106,18 +105,10 @@ function AllGuidesPageContent(): ReactNode {
})
: undefined;
return (
-
+
= {};
+
+ const files = getFiles(samplesDir)
+ .filter((f) => /\.(md|mdx)$/.test(f))
+ .filter((f) => {
+ const relativePath = path.relative(samplesDir, f);
+ const normalized = relativePath.split(path.sep).join("/");
+ return normalized !== "home.mdx";
+ });
+
+ const samples = files.map((filePath) => {
+ const fileContent = fs.readFileSync(filePath, "utf-8");
+ const { data } = matter(fileContent);
+
+ const relativePath = path.relative(samplesDir, filePath);
+ const relativePathNormalized = relativePath.split(path.sep).join("/");
+ const baseName = relativePathNormalized.replace(/\.(md|mdx)$/, "");
+
+ const slug = baseName.endsWith("/index") ? baseName.replace(/\/index$/, "") : baseName;
+ const permalink = `/samples/${slug === "index" ? "" : slug}`;
+
+ const allTagsArray: Array<{ key: string; category: string }> = [];
+
+ const challengesSolutionsTags = data.challenges_solutions_tags;
+
+ if (Array.isArray(challengesSolutionsTags)) {
+ challengesSolutionsTags.forEach((tag: string) => {
+ allTagsArray.push({ key: tag, category: "challenges-solutions" });
+ });
+ }
+
+ const featureTags = data.feature_tags;
+ if (Array.isArray(featureTags)) {
+ featureTags.forEach((tag: string) => {
+ allTagsArray.push({ key: tag, category: "feature" });
+ });
+ }
+
+ const techStackTags = data.tech_stack_tags;
+ if (Array.isArray(techStackTags)) {
+ techStackTags.forEach((tag: string) => {
+ allTagsArray.push({ key: tag, category: "tech-stack" });
+ });
+ }
+
+ allTagsArray.forEach(({ key }) => {
+ tagCounts[key] = (tagCounts[key] || 0) + 1;
+ });
+
+ const formattedTags = allTagsArray.map(({ key, category }) => {
+ const categoryTags = tagsByCategory[category];
+ const definedTag = categoryTags[key];
+
+ return {
+ label: definedTag?.label || key,
+ key,
+ category,
+ };
+ });
+
+ return {
+ id: path.basename(filePath, path.extname(filePath)),
+ title: data.title,
+ permalink: data.slug || permalink,
+ tags: formattedTags,
+ description: data.description,
+ image: data.image,
+ img_alt: data.img_alt,
+ };
+ });
+
+ const allTags: Array<{
+ label: string;
+ key: string;
+ count: number;
+ category: string;
+ }> = [];
+
+ Object.entries(tagsByCategory).forEach(([category, tags]) => {
+ Object.entries(tags).forEach(([key, value]) => {
+ allTags.push({
+ label: value.label,
+ key,
+ count: tagCounts[key] || 0,
+ category,
+ });
+ });
+ });
+
+ return {
+ samples: samples,
+ tags: allTags,
+ };
+ },
+ async contentLoaded({ content, actions }) {
+ const { setGlobalData } = actions;
+ setGlobalData(content);
+ },
+ };
+}
diff --git a/src/theme/DocItem/Authors/index.tsx b/src/theme/DocItem/Authors/index.tsx
index 1bba0891f8..5daefadef7 100644
--- a/src/theme/DocItem/Authors/index.tsx
+++ b/src/theme/DocItem/Authors/index.tsx
@@ -18,7 +18,6 @@ type Author = {
function getAuthorData(authorKey: string): Author | null {
const authorInfo = authorsData[authorKey];
if (!authorInfo) {
- // eslint-disable-next-line no-console
console.warn(`No author data found for key '${authorKey}' in authors.json`);
return null;
}
@@ -63,15 +62,15 @@ const socialIconMap: Record = {
export default function DocItemAuthors() {
const { frontMatter } = useDoc();
- const { publishedAt, author: authorKey } = frontMatter;
+ const { published_at, author: authorKey } = frontMatter;
- if (!authorKey && !publishedAt) {
+ if (!authorKey && !published_at) {
return null;
}
const author = authorKey ? getAuthorData(authorKey) : null;
- if (!author && !publishedAt) {
+ if (!author && !published_at) {
return null;
}
@@ -122,10 +121,10 @@ export default function DocItemAuthors() {
)}
- {publishedAt && (
+ {published_at && (
Published on{" "}
- {new Date(publishedAt).toLocaleDateString("en-US", {
+ {new Date(published_at).toLocaleDateString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
diff --git a/src/theme/DocItem/BannerImage/index.tsx b/src/theme/DocItem/BannerImage/index.tsx
index 9a0634a55e..b1bc65db3f 100644
--- a/src/theme/DocItem/BannerImage/index.tsx
+++ b/src/theme/DocItem/BannerImage/index.tsx
@@ -6,7 +6,7 @@ import { IconName } from "@site/src/typescript/iconName";
import LazyImage from "@site/src/components/Common/LazyImage";
export interface BannerImageProps {
- imgSrc?: string | { light: string; dark: string };
+ imgSrc?: string;
imgAlt?: string;
imgIcon?: IconName;
className?: string;
diff --git a/src/theme/DocItem/Metadata/DocPageMetadata.tsx b/src/theme/DocItem/Metadata/DocPageMetadata.tsx
index 0d9a4c0d65..42b9f29431 100644
--- a/src/theme/DocItem/Metadata/DocPageMetadata.tsx
+++ b/src/theme/DocItem/Metadata/DocPageMetadata.tsx
@@ -16,12 +16,17 @@ export interface DocPageMetadataProps {
canonicalUrl: string;
ogImageUrl: string;
// Shared (optional)
- lastUpdatedAt?: number;
+ lastUpdatedAt?: number | null;
+ keywords?: string[];
// Guide-only (optional)
proficiencyLevel?: string;
authorKey?: string;
publishedAt?: string;
- keywords?: string[];
+ // Sample-only (optional)
+ schemaType?: "TechArticle" | "SoftwareSourceCode";
+ repositoryUrl?: string;
+ licenseUrl?: string;
+ languages?: string[];
}
export default function DocPageMetadata({
@@ -34,9 +39,46 @@ export default function DocPageMetadata({
authorKey,
publishedAt,
keywords,
+ schemaType = "TechArticle",
+ repositoryUrl,
+ licenseUrl,
+ languages,
}: DocPageMetadataProps): ReactNode {
const authorInfo = authorKey ? authorsData[authorKey as keyof typeof authorsData] : null;
+ // Generate SoftwareSourceCode schema for samples
+ if (schemaType === "SoftwareSourceCode") {
+ const softwareSourceCodeJsonLd = JSON.stringify({
+ "@context": "https://schema.org",
+ "@type": "SoftwareSourceCode",
+ name: title,
+ ...(description ? { description } : {}),
+ url: canonicalUrl,
+ ...(repositoryUrl ? { codeRepository: repositoryUrl } : {}),
+ ...(licenseUrl ? { license: licenseUrl } : {}),
+ ...(languages?.length ? { programmingLanguage: languages } : {}),
+ ...(keywords?.length ? { keywords } : {}),
+ runtimePlatform: "RavenDB",
+ publisher: {
+ "@type": "Organization",
+ name: "RavenDB",
+ url: "https://ravendb.net",
+ },
+ isPartOf: {
+ "@type": "CollectionPage",
+ "@id": `${canonicalUrl.split("/samples/")[0]}/samples`,
+ name: "RavenDB Code Samples",
+ },
+ });
+
+ return (
+
+
+
+ );
+ }
+
+ // Generate TechArticle schema for guides and docs
const techArticleJsonLd = JSON.stringify({
"@context": "https://schema.org",
"@type": "TechArticle",
diff --git a/src/theme/DocItem/Metadata/index.tsx b/src/theme/DocItem/Metadata/index.tsx
index 55db8ac27f..f437323fbf 100644
--- a/src/theme/DocItem/Metadata/index.tsx
+++ b/src/theme/DocItem/Metadata/index.tsx
@@ -21,16 +21,18 @@ export default function MetadataWrapper(props: Props): ReactNode {
const isCloud = source?.startsWith("@site/cloud/") || source?.startsWith("cloud/") || false;
const isTemplate = source?.startsWith("@site/templates/") || source?.startsWith("templates/") || false;
const isDocumentationPage = !isGuide && !isCloud && !isTemplate;
+ const isSample = source?.startsWith("@site/samples/") || source?.startsWith("samples/") || false;
- // Exclude landing pages (e.g. guides/home.mdx) from guide-specific metadata
+ // Exclude landing pages (e.g. guides/home.mdx, samples/home.mdx) from type-specific metadata
const fileName = source?.split("/").pop();
const isGuidePage = isGuide && fileName !== "home.mdx";
+ const isSamplePage = isSample && fileName !== "home.mdx";
// Strip trailing slash from base URL to avoid double slashes
const baseUrl = (siteConfig.url as string).replace(/\/$/, "");
const canonicalUrl = (
isDocumentationPage
- ? `${baseUrl}/${siteConfig.customFields.latestVersion}${metadata.slug}`
+ ? `${baseUrl}/${siteConfig.customFields?.latestVersion}${metadata.slug}`
: `${baseUrl}${permalink}`
).replace(/\/$/, "");
@@ -76,6 +78,23 @@ export default function MetadataWrapper(props: Props): ReactNode {
lastUpdatedAt={metadata.lastUpdatedAt}
/>
)}
+ {isSamplePage && (
+ tag.replace(/-/g, " "))}
+ />
+ )}
["frontMatter"];
canonicalUrl: string;
ogImageUrl: string;
@@ -105,19 +124,19 @@ function ValidatedGuideDocPageMetadata({
if (!title) {
throw new Error(`Guide "${permalink}" is missing a required "title" in frontmatter.`);
}
- if (!frontMatter.proficiencyLevel) {
- throw new Error(`Guide "${permalink}" is missing a required "proficiencyLevel" in frontmatter.`);
+ if (!frontMatter.proficiency_level) {
+ throw new Error(`Guide "${permalink}" is missing a required "proficiency_level" in frontmatter.`);
}
return (
;
@@ -11,6 +12,8 @@ export default function DocItemWrapper(props: Props): ReactNode {
const title = props.content.metadata?.title;
const source = props.content.metadata?.source as string | undefined;
const frontMatter = props.content.frontMatter as CustomDocFrontMatter;
+ const activePlugin = useActivePlugin();
+ const pluginId = activePlugin?.pluginId;
const isDocsOrVersioned =
source?.startsWith("@site/docs/") ||
@@ -25,8 +28,15 @@ export default function DocItemWrapper(props: Props): ReactNode {
const showTopbar = Boolean(isDocsOrVersioned && !isExcluded);
+ const isTemplatesPlugin = pluginId === "templates";
+
return (
<>
+ {isTemplatesPlugin && (
+
+
+
+ )}
{showTopbar &&
diff --git a/src/theme/DocSidebar/Desktop/index.tsx b/src/theme/DocSidebar/Desktop/index.tsx
index 227d09dcf4..bf55cb4632 100644
--- a/src/theme/DocSidebar/Desktop/index.tsx
+++ b/src/theme/DocSidebar/Desktop/index.tsx
@@ -30,6 +30,8 @@ function DocSidebarDesktop({ path, sidebar, onCollapse, isHidden }: Props) {
const pathType = getPathType(path);
const landingPagePath = getLandingPagePath(pathType, versionLabel);
+ const shouldDisplayContent = pathType !== PathType.Guides && pathType !== PathType.Samples;
+
return (
} + {shouldDisplayContent &&
} {pathType === PathType.Documentation &&
);
diff --git a/src/theme/DocSidebar/Mobile/index.tsx b/src/theme/DocSidebar/Mobile/index.tsx
index efc62ea098..f9fd75907d 100644
--- a/src/theme/DocSidebar/Mobile/index.tsx
+++ b/src/theme/DocSidebar/Mobile/index.tsx
@@ -22,6 +22,8 @@ function DocSidebarMobileSecondaryMenu({ sidebar, path }: DocSidebarProps) {
const pathType = getPathType(path);
const landingPagePath = getLandingPagePath(pathType, versionLabel);
+ const shouldDisplayContent = pathType !== PathType.Guides && pathType !== PathType.Samples;
+
return (
)}
+ {pathType !== PathType.Samples && (
+
+
- {pathType !== PathType.Guides && } + {shouldDisplayContent &&
} {pathType === PathType.Documentation &&
-
@@ -47,6 +49,14 @@ function DocSidebarMobileSecondaryMenu({ sidebar, path }: DocSidebarProps) {
)}
+ {pathType !== PathType.Samples && (
+
+
Samples + + Switch + + + )} {pathType !== PathType.Cloud && ( RavenDB Cloud Docs @@ -59,7 +69,7 @@ function DocSidebarMobileSecondaryMenu({ sidebar, path }: DocSidebarProps) { Community - {pathType !== PathType.Cloud && pathType !== PathType.Guides && ( + {pathType === PathType.Documentation && ( - )} - {pathType !== PathType.Guides && ( + {shouldDisplayContent && (
-
)}
- {pathType !== PathType.Cloud && pathType !== PathType.Guides &&
- {sortedItems.map((doc, index) => {
+ {sortedItems.map((doc) => {
const guide = guides.find((g: Guide) => g.permalink === doc.permalink);
const formattedDate = guide?.lastUpdatedAt
? new Date(guide.lastUpdatedAt * 1000).toLocaleDateString("en-US", {
@@ -123,18 +122,10 @@ function DocTagDocListPageContent({ tag }: Props): ReactNode {
})
: undefined;
return (
-
+
,
- // eslint-disable-next-line no-undef
- React.HTMLAttributes {
+export interface Props extends Partial, React.HTMLAttributes {
children?: React.ReactNode;
to?: string;
size?: "xs" | "default";
diff --git a/src/typescript/docMetadata.d.ts b/src/typescript/docMetadata.d.ts
index d40e3f782d..f6219efc5d 100644
--- a/src/typescript/docMetadata.d.ts
+++ b/src/typescript/docMetadata.d.ts
@@ -3,15 +3,41 @@ import { DocsLanguage } from "@site/src/components/LanguageStore";
import { SeeAlsoItemType } from "@site/src/components/SeeAlso/types";
import { IconName } from "@site/src/typescript/iconName";
+export interface GalleryImage {
+ src: string;
+ alt?: string;
+}
+
+export interface RelatedResourceFrontMatter {
+ type: "guide" | "documentation" | "video";
+ documentation_type?: "docs" | "cloud";
+ subtitle: string;
+ article_key?: string;
+ url?: string;
+}
+
export interface CustomDocFrontMatter extends DocFrontMatter {
supported_languages?: DocsLanguage[];
see_also?: SeeAlsoItemType[];
author?: string;
icon?: IconName;
- image?: string | { light: string; dark: string };
- publishedAt?: string;
- proficiencyLevel?: string;
+ image?: string;
+ img_alt?: string;
+ published_at?: string;
+ proficiency_level?: string;
keywords?: string[];
+ gallery?: GalleryImage[];
+ challenges_solutions_tags?: string[];
+ feature_tags?: string[];
+ tech_stack_tags?: string[];
+ category?: string;
+ license?: string;
+ license_url?: string;
+ repository_url?: string;
+ demo_url?: string;
+ languages?: string[];
+ external_url?: string;
+ related_resources?: RelatedResourceFrontMatter[];
}
type CustomDocContextValue = Omit & {
diff --git a/src/typescript/pathUtils.ts b/src/typescript/pathUtils.ts
index 438fe3e043..48abb5d651 100644
--- a/src/typescript/pathUtils.ts
+++ b/src/typescript/pathUtils.ts
@@ -3,6 +3,7 @@ export const PathType = {
Guides: "GUIDES",
Documentation: "DOCUMENTATION",
Templates: "TEMPLATES",
+ Samples: "SAMPLES",
} as const;
export type PathTypeValue = (typeof PathType)[keyof typeof PathType];
@@ -14,6 +15,9 @@ export function getPathType(path: string): PathTypeValue {
if (path.includes("/guides")) {
return PathType.Guides;
}
+ if (path.includes("/samples")) {
+ return PathType.Samples;
+ }
if (path.includes("/templates")) {
return PathType.Templates;
}
@@ -27,6 +31,9 @@ export function getLandingPagePath(pathType: PathTypeValue, versionLabel: string
if (pathType === PathType.Guides) {
return "/guides";
}
+ if (pathType === PathType.Samples) {
+ return "/samples";
+ }
if (pathType === PathType.Templates) {
return "/templates";
}
diff --git a/static/img/samples/library-of-ravens/01.webp b/static/img/samples/library-of-ravens/01.webp
new file mode 100644
index 0000000000..83addb6c52
Binary files /dev/null and b/static/img/samples/library-of-ravens/01.webp differ
diff --git a/static/img/samples/library-of-ravens/02.webp b/static/img/samples/library-of-ravens/02.webp
new file mode 100644
index 0000000000..a99e320f42
Binary files /dev/null and b/static/img/samples/library-of-ravens/02.webp differ
diff --git a/static/img/samples/library-of-ravens/03.webp b/static/img/samples/library-of-ravens/03.webp
new file mode 100644
index 0000000000..2122e3a367
Binary files /dev/null and b/static/img/samples/library-of-ravens/03.webp differ
diff --git a/static/img/samples/library-of-ravens/cover.webp b/static/img/samples/library-of-ravens/cover.webp
new file mode 100644
index 0000000000..d60815d443
Binary files /dev/null and b/static/img/samples/library-of-ravens/cover.webp differ
diff --git a/static/llms.txt b/static/llms.txt
index c5eb0d8c5f..652c498398 100644
--- a/static/llms.txt
+++ b/static/llms.txt
@@ -149,6 +149,11 @@ Documentation is versioned. The current version is 7.2. Use the `/7.2/` URL pref
- [Data Migration](https://docs.ravendb.net/7.2/migration/server/data-migration): Migrate data between RavenDB versions
- [Breaking Changes](https://docs.ravendb.net/7.2/migration/server/server-breaking-changes): Server-side breaking changes by version
+## Sample Applications
+
+- [Samples Home](https://docs.ravendb.net/samples/): Browse production-ready code samples, architecture patterns, and starter kits built with RavenDB
+- [The Library of Ravens](https://docs.ravendb.net/samples/the-ravens-library): Library management app demonstrating vector search, Azure Storage Queues ETL, Include for N+1 elimination, and Document Refresh — built with C#, Aspire, and Azure Functions
+
## Cloud
- [RavenDB Cloud Documentation](https://docs.ravendb.net/cloud/): Cloud service portal documentation
diff --git a/templates/authors.mdx b/templates/authors.mdx
index c5bd3c277d..e0e7fb0382 100644
--- a/templates/authors.mdx
+++ b/templates/authors.mdx
@@ -12,10 +12,6 @@ see_also:
import Admonition from "@theme/Admonition";
import Panel from "@site/src/components/Panel";
-
-
-
-
# Authors
## Add a new author
diff --git a/templates/best-practices-samples.mdx b/templates/best-practices-samples.mdx
new file mode 100644
index 0000000000..1cb1d679ae
--- /dev/null
+++ b/templates/best-practices-samples.mdx
@@ -0,0 +1,274 @@
+---
+title: "Samples: Best practices"
+hide_table_of_contents: false
+sidebar_label: Best practices
+see_also:
+ - title: "Adding new samples"
+ link: "/templates/new-samples"
+ source: "docs"
+ path: "Templates > Samples"
+ - title: "Samples Introduction"
+ link: "/templates/introduction-samples"
+ source: "docs"
+ path: "Templates > Samples"
+---
+
+import Admonition from "@theme/Admonition";
+import Panel from "@site/src/components/Panel";
+
+Guidelines and recommendations for creating high-quality sample documentation.
+
+## Content Guidelines
+
+### Tag Selection
+
+**Challenges & Solutions Tags:**
+- Focus on primary business problems
+- Be specific: `semantic-search` not just `search`
+
+**Feature Tags:**
+- Select key RavenDB features
+- Prioritize features with code examples
+- Include both basic and advanced features
+
+**Tech Stack Tags:**
+- List all major technologies
+- Include language, framework, and cloud services
+- Order by importance: language first, then frameworks
+
+**Example:**
+
+```yaml
+challenges_solutions_tags: [semantic-search, integration-patterns]
+feature_tags: [vector-search, include, document-refresh, azure-storage-queues-etl]
+tech_stack_tags: [csharp, aspire, azure-storage-queues, azure-functions]
+```
+
+### Images
+
+**Cover Image:**
+- Recommended size: 1200x630px
+- Format: WebP for best compression
+- Show the app in action, not just a logo
+- Use high-quality screenshots
+- Ensure text is readable
+
+**Gallery Screenshots:**
+- At least 2 images showing key features
+- Consistent size and aspect ratio
+- Add descriptive alt text
+- Show different parts of the app
+- Highlight unique features
+
+**File organization:**
+
+```
+static/img/samples/{sample-name}/
+├── cover.webp # Main cover image
+├── 01.webp # Gallery image 1
+├── 02.webp # Gallery image 2
+└── 03.webp # Gallery image 3
+```
+
+## Structure Guidelines
+
+### Features Section
+
+Use `FeatureAccordion` components for each major feature:
+
+**Guidelines:**
+- 3-5 accordions per sample
+- Order by importance
+
+**Template:**
+
+```mdx
+## Features used
+
+
+ [Detailed explanation of how and why this feature is used]
+
+ Implementation example:
+
+ // Code showing the feature in action
+
+ [Additional context or benefits]
+
+```
+
+### Related Resources
+
+**Guidelines:**
+- Link to 2-3 related resources
+- Mix guides and documentation
+
+**Priority order:**
+1. Related guides (how-to articles)
+2. Feature documentation (RavenDB docs)
+3. Cloud documentation (if applicable)
+
+## Component Usage
+
+### Sidebar (frontmatter-driven)
+
+The metadata sidebar is fully driven by frontmatter — no JSX props needed.
+
+**Actions (repository_url / demo_url):**
+- Always provide `repository_url` if the code is public
+- Add `demo_url` only if a live demo is available and maintained
+- Don't link to private repositories or broken demo URLs
+
+**Related resources (related_resources):**
+- Link to 2–3 related resources
+- Mix guides and documentation
+- Verify links are correct and current; use descriptive `subtitle` values
+- Don't link to deprecated documentation, use vague subtitles like "Related Article", or duplicate links
+
+### FeatureAccordion
+
+**Do:**
+- Use descriptive icons matching the feature
+- Keep descriptions to one sentence
+
+**Don't:**
+- Leave children empty (omit the accordion instead)
+- Include broken code examples
+
+## Tag Management
+
+### Adding New Tags
+
+**Before adding a tag:**
+1. Check if a similar tag exists
+2. Verify it fits the category (challenges-solutions/feature/tech-stack)
+3. Ensure it will be used by multiple samples
+4. Use consistent naming conventions
+
+**Naming conventions:**
+- Use kebab-case: `azure-storage-queues` not `AzureStorageQueues`
+- Be specific: `azure-storage-queues-etl` not `etl`
+- Avoid abbreviations: `semantic-search` not `sem-search`
+- Use full names: `csharp` not `cs`
+
+### Tag Maintenance
+
+**Periodically review:**
+- Unused tags (count = 0)
+- Duplicate or similar tags
+- Outdated technology tags
+- Inconsistent naming
+
+## Common Mistakes
+
+### ❌ Missing Required Frontmatter
+
+```yaml
+---
+title: "My Sample"
+# Missing description, tags
+---
+```
+
+### ✅ Complete Frontmatter
+
+```yaml
+---
+title: "My Sample"
+description: "Complete description"
+challenges_solutions_tags: [semantic-search]
+feature_tags: [vector-search]
+tech_stack_tags: [csharp]
+license: "MIT License"
+license_url: "https://opensource.org/licenses/MIT"
+repository_url: "https://github.com/ravendb/my-sample-repo"
+languages: ["C#"]
+---
+```
+
+### ❌ Adding H1 Heading
+
+```mdx
+---
+title: "My Sample"
+---
+
+# My Sample
+
+## Overview
+```
+
+### ✅ Start with H2
+
+```mdx
+---
+title: "My Sample"
+---
+
+## Overview
+```
+
+### ❌ Undefined Tags
+
+```yaml
+challenges_solutions_tags: [nonexistent-tag] # Tag doesn't exist in YAML
+```
+
+### ✅ Valid Tags
+
+```yaml
+challenges_solutions_tags: [semantic-search] # Tag exists in samples/tags/challenges-solutions.yml
+```
+
+### ❌ Empty FeatureAccordion
+
+```tsx
+
+ {/* Empty - don't do this */}
+
+```
+
+### ✅ Complete FeatureAccordion
+
+```tsx
+
+ Detailed explanation with code examples...
+
+```
+
+## Testing Checklist
+
+Before publishing a sample:
+
+- [ ] All frontmatter fields are present and valid
+- [ ] `repository_url` and `languages` are set (feeds `SoftwareSourceCode` JSON-LD)
+- [ ] All tags exist in their respective YAML files
+- [ ] Cover image loads correctly
+- [ ] Gallery images load and have alt text
+- [ ] GitHub repository link works
+- [ ] Demo URL works (if provided)
+- [ ] All related resource links work
+- [ ] Code examples are syntactically correct
+- [ ] Sample appears in hub page grid
+- [ ] Filtering works with all tags
+- [ ] Metadata sidebar displays correctly
+- [ ] No console errors or warnings
+
+## Performance Tips
+
+**Images:**
+- Use WebP format for smaller file sizes
+- Optimize images before committing
+- Use appropriate dimensions (don't serve 4K images)
+
+**Code Examples:**
+- Keep examples concise
+- Use syntax highlighting
+
+**Content:**
+- Keep descriptions brief
+- Link to external resources instead of duplicating content
+
diff --git a/templates/components-samples.mdx b/templates/components-samples.mdx
new file mode 100644
index 0000000000..f1cc582992
--- /dev/null
+++ b/templates/components-samples.mdx
@@ -0,0 +1,228 @@
+---
+title: "Samples: Components"
+hide_table_of_contents: false
+sidebar_label: Components
+see_also:
+ - title: "Adding new samples"
+ link: "/templates/new-samples"
+ source: "docs"
+ path: "Templates > Samples"
+ - title: "Samples Introduction"
+ link: "/templates/introduction-samples"
+ source: "docs"
+ path: "Templates > Samples"
+---
+
+import Admonition from "@theme/Admonition";
+import Panel from "@site/src/components/Panel";
+
+This guide documents all React components used in the Samples system.
+
+## Import Statement
+
+All sample components are exported from a single entry point:
+
+```tsx
+import {
+ // Layout (includes sidebar and gallery automatically)
+ SampleLayout,
+
+ // Content
+ FeatureAccordion,
+
+ // Hub (not imported in sample pages)
+ SamplesHomePage,
+ SampleCard,
+ SamplesGrid,
+ SamplesFilter,
+} from '@site/src/components/Samples';
+```
+
+## Layout Components
+
+### SampleLayout
+
+Two-column responsive layout for sample detail pages. Renders the metadata sidebar and gallery automatically from frontmatter — no props needed beyond `children`.
+
+**Location:** `src/components/Samples/Overview/SampleLayout.tsx`
+
+**Props:**
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | ✅ | Main content area |
+
+**Usage:**
+
+```tsx
+
+ {/* Main content */}
+
+```
+
+**Auto-rendered from frontmatter:**
+- Sidebar — `SampleMetadataColumn` (tags, actions, license, related resources)
+- Gallery — `gallery` field; omitted automatically when the field is absent
+
+**Behavior:**
+- Desktop (lg+): Two columns, sidebar on right (300px fixed width); gallery above content
+- Mobile: Stacked, sidebar and gallery appear above content
+
+---
+
+## Metadata Sidebar Components
+
+### SampleMetadataColumn
+
+Container for the metadata sidebar. Reads all data from frontmatter — no props required.
+
+**Location:** `src/components/Samples/Overview/Partials/SampleMetadataColumn.tsx`
+
+**Props:**
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `className` | `string` | ❌ | Additional CSS classes |
+
+**Usage:**
+
+```tsx
+
+ Detailed explanation of how vector search is used...
+
+ // Code example
+
+```
+
+**Behavior:**
+- Click header to expand/collapse
+- Smooth animation with Framer Motion
+- Chevron icon rotates on expand/collapse
+
+---
+
+## Hub Components
+
+These components power the `/samples` hub page. They are typically not used in individual sample pages.
+
+### SamplesHomePage
+
+Main hub page component with filters and grid.
+
+**Location:** `src/components/Samples/Hub/SamplesHomePage.tsx`
+
+**Usage:**
+
+```mdx
+---
+title: Samples
+slug: /
+---
+
+import { SamplesHomePage } from "@site/src/components/Samples";
+
+
+ All components are re-exported from `src/components/Samples/index.ts` for convenient importing.
+
+
diff --git a/templates/featured-guides.mdx b/templates/featured-guides.mdx
index 7ade1167af..59d715022a 100644
--- a/templates/featured-guides.mdx
+++ b/templates/featured-guides.mdx
@@ -16,10 +16,6 @@ see_also:
import Admonition from "@theme/Admonition";
import Panel from "@site/src/components/Panel";
-
-
-
-
# Featured guides
## Mark a guide as featured
@@ -50,7 +46,7 @@ import FeaturedGuides from "@site/src/components/Guides/FeaturedGuides";
```mdx
---
title: "Example Guide"
- publishedAt: 2026-02-27
+ published_at: 2026-02-27
author: "Author Name"
tags: [ai, demo]
image: "/img/guides-ai-agents.webp"
@@ -71,5 +67,5 @@ import FeaturedGuides from "@site/src/components/Guides/FeaturedGuides";
section will update automatically.
- If you omit the `guidesTitles` prop, `FeaturedGuides` will fall back to showing the two most recently updated guides based on file timestamps or `publishedAt`.
+ If you omit the `guidesTitles` prop, `FeaturedGuides` will fall back to showing the two most recently updated guides based on file timestamps or `published_at`.
diff --git a/templates/filtering-samples.mdx b/templates/filtering-samples.mdx
new file mode 100644
index 0000000000..26b3c7b594
--- /dev/null
+++ b/templates/filtering-samples.mdx
@@ -0,0 +1,173 @@
+---
+title: "Samples: Filtering"
+hide_table_of_contents: false
+sidebar_label: Filtering
+see_also:
+ - title: "Samples Introduction"
+ link: "/templates/introduction-samples"
+ source: "docs"
+ path: "Templates > Samples"
+ - title: "Sample tags"
+ link: "/templates/tags-samples"
+ source: "docs"
+ path: "Templates > Samples"
+---
+
+import Admonition from "@theme/Admonition";
+import Panel from "@site/src/components/Panel";
+
+The Samples hub page features a powerful filtering system with URL-based state, multi-category tag selection, and flexible match logic.
+
+## Features
+
+### 1. Multi-Category Filtering
+
+Tags are organized into three categories:
+- **Challenges & Solutions** - Business problems solved
+- **Features** - RavenDB features demonstrated
+- **Tech Stack** - Technologies used
+
+Users can select tags from any or all categories simultaneously.
+
+### 2. Match Logic Toggle
+
+Two matching modes:
+- **Any** (OR logic) - Show samples matching *any* selected tag
+- **All** (AND logic) - Show samples matching *all* selected tags
+
+### 3. URL-Based State
+
+Filter state is stored in URL query parameters for:
+- Shareable filtered views
+- Browser back/forward navigation
+- Bookmarkable searches
+
+**Example URLs:**
+```
+/samples?tags=vector-search
+/samples?tags=vector-search,include&match=all
+/samples?tags=csharp,aspire
+```
+
+### 4. Tag Search
+
+Filter sidebar includes a search box to quickly find tags by name.
+
+### 5. Expandable Categories
+
+Each category can be expanded/collapsed independently. Categories with many tags show only the first 5 by default with a "More" button.
+
+## User Flows
+
+### Flow 1: Browse and Filter
+
+1. User visits `/samples`
+2. Sees all samples in grid
+3. Clicks "Vector Search" tag in filter sidebar
+4. URL updates to `/samples?tags=vector-search`
+5. Grid filters to show only samples with vector search
+6. User clicks "Include" tag
+7. URL updates to `/samples?tags=vector-search,include`
+8. Grid shows samples with *either* tag (Any mode)
+
+### Flow 2: Refine with AND Logic
+
+1. User has selected `vector-search` and `include` tags
+2. Switches match logic from "Any" to "All"
+3. URL updates to `/samples?tags=vector-search,include&match=all`
+4. Grid shows only samples with *both* tags
+
+### Flow 3: Quick Filter from Card
+
+1. User sees a sample card with "C#" language badge
+2. Clicks the "C#" badge
+3. All filters clear, only "C#" is selected
+4. URL updates to `/samples?tags=csharp`
+5. Grid shows all C# samples
+
+### Flow 4: Share Filtered View
+
+1. User has filtered to `csharp,aspire` with "All" logic
+2. Copies URL: `/samples?tags=csharp,aspire&match=all`
+3. Shares URL with colleague
+4. Colleague opens URL and sees the same filtered view
+
+## UI Components
+
+### SamplesFilter
+
+**Features:**
+- Search box for filtering tags by name
+- Match logic toggle (Any/All)
+- Clear filters button
+- Expandable categories
+- Tag checkboxes with counts
+
+**Props:**
+
+```typescript
+interface SamplesFilterProps {
+ categories: FilterCategoryData[];
+ selectedTags: Set;
+ onTagToggle: (tagKey: string) => void;
+ matchLogic: "any" | "all";
+ onMatchLogicChange: (logic: "any" | "all") => void;
+ onClearFilters?: () => void;
+}
+```
+
+### FilterCategory
+
+**Features:**
+- Collapsible category header
+- Shows first 5 tags by default
+- "More" button to expand remaining tags
+- Checkbox for each tag with label
+
+**Props:**
+
+```typescript
+interface FilterCategoryProps {
+ name: string;
+ label: string;
+ tags: FilterTag[];
+ selectedTags: Set;
+ onTagToggle: (tagKey: string) => void;
+ isExpanded: boolean;
+ onToggleExpanded: () => void;
+}
+```
+
+### SamplesGrid
+
+**Features:**
+- Displays filtered samples
+- Shows sample count badge
+- Responsive grid (1 column mobile, 2 columns desktop)
+- Staggered animation on load
+
+**Props:**
+
+```typescript
+interface SamplesGridProps {
+ samples: Sample[];
+ selectedTags: Set;
+ matchLogic: "any" | "all";
+ onTagClick?: (tagKey: string) => void;
+}
+```
+
+## Styling
+
+### Active Tag State
+
+Selected tags are highlighted in the filter sidebar:
+
+```tsx
+ onTagToggle(tag.key)}
+ label={tag.label}
+/>
+```
diff --git a/templates/frames.mdx b/templates/frames.mdx
index b1bbadf41f..c5964d7e3b 100644
--- a/templates/frames.mdx
+++ b/templates/frames.mdx
@@ -10,10 +10,6 @@ import Panel from '@site/src/components/Panel';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-
-
-
-
# Frames overview
This guide shows how to use content frames in MDX: lightweight `ContentFrame` for small/medium chunks and `Panel` for larger sections with a built‑in heading and body.
@@ -26,15 +22,13 @@ import ContentFrame from '@site/src/components/ContentFrame';
```
### Basic usage
-````mdx
+```mdx
Text, lists, images, and even code blocks.
- ```ts
- console.log('Hello world!')
- ```
+ // Code example
-````
+```
#### Live example
@@ -167,41 +161,31 @@ You can combine `Panel` and `ContentFrame`:
### Panels with code and tabs
-````mdx
+```mdx
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
- ```csharp
- // sample code
- Console.WriteLine("Hello");
- ```
+ // Code example 1
- ```csharp
- await Console.Out.WriteLineAsync("Hello");
- ```
+ // Code example 2
-````
+```
#### Live example
- ```csharp
- // sample code
- Console.WriteLine("Hello");
- ```
+ // Code example 1
- ```csharp
- await Console.Out.WriteLineAsync("Hello");
- ```
+ // Code example 2
diff --git a/templates/gallery-example.mdx b/templates/gallery-example.mdx
new file mode 100644
index 0000000000..fb362c7751
--- /dev/null
+++ b/templates/gallery-example.mdx
@@ -0,0 +1,97 @@
+---
+title: "Gallery Component Example"
+description: "Example of using the Gallery component with multiple images"
+gallery:
+ - src: "/img/samples/library-of-ravens/01.webp"
+ alt: "First example image"
+ - src: "/img/samples/library-of-ravens/02.webp"
+ alt: "Second example image"
+ - src: "/img/samples/library-of-ravens/03.webp"
+ alt: "Third example image"
+ - src: "/img/discord.webp"
+ alt: "Fourth example image"
+ - src: "/img/webinar.webp"
+ alt: "Fifth example image"
+---
+
+import Gallery from '@site/src/components/Common/Gallery';
+
+# Gallery Component Example
+
+This page demonstrates how to use the Gallery component with images defined in frontmatter.
+
+## Basic Usage
+
+The Gallery component provides responsive layouts optimized for each device:
+
+### Desktop (≥ lg breakpoint)
+- One large image on the left (taking ~2/3 of the width)
+- Two smaller images stacked on the right (taking ~1/3 of the width)
+- If there are more than 3 images, a "+x" overlay appears on the third image
+
+### Mobile (< lg breakpoint)
+- Single-image carousel with swipe navigation
+- All images accessible via horizontal scroll
+- Dot indicators showing current position
+- Tap dots to jump to specific images
+- Images display in their natural aspect ratio
+
+### Example Gallery
+
+
+ Unlike Guides which use a single `tags.yml` file, Samples organize tags into separate category files. This enables the filter UI to group tags logically and allows for "Any/All" matching within categories.
+
+
+## File Structure
+
+```
+samples/
+├── home.mdx # Hub page (uses SamplesHomePage component)
+├── the-ravens-library.mdx # Example sample
+├── tags/
+│ ├── challenges-solutions.yml # Challenges & solutions tags
+│ ├── feature.yml # RavenDB feature tags
+│ └── tech-stack.yml # Technology stack tags
+└── ... # Additional sample files
+
+src/components/Samples/
+├── Hub/ # Hub page components
+│ ├── SamplesHomePage.tsx
+│ └── Partials/
+│ ├── SampleCard.tsx
+│ ├── SamplesGrid.tsx
+│ ├── SamplesFilter.tsx
+│ ├── FilterCategory.tsx
+│ ├── SamplesHeader.tsx
+│ └── SamplesDecoration.tsx
+├── Overview/ # Detail page components
+│ ├── SampleLayout.tsx
+│ └── Partials/
+│ ├── SampleMetadataColumn.tsx
+│ ├── ActionsCard.tsx
+│ ├── RelatedResource.tsx
+│ └── FeatureAccordion.tsx
+├── index.ts # Component exports
+└── types.ts # TypeScript types
+
+src/plugins/
+└── recent-samples-plugin.ts # Indexing plugin
+```
+
diff --git a/templates/introduction.mdx b/templates/introduction.mdx
index 3cc39ff65c..ac6233ed75 100644
--- a/templates/introduction.mdx
+++ b/templates/introduction.mdx
@@ -8,10 +8,6 @@ import CardWithImage from "@site/src/components/Common/CardWithImage";
import CardWithImageHorizontal from "@site/src/components/Common/CardWithImageHorizontal";
import ColGrid from "@site/src/components/ColGrid";
-
-
-
-
# Start template
Use RavenDB to ship AI functionalities faster
diff --git a/templates/new-guides.mdx b/templates/new-guides.mdx
index 17de6c17d0..9494184ae2 100644
--- a/templates/new-guides.mdx
+++ b/templates/new-guides.mdx
@@ -17,10 +17,6 @@ import Admonition from "@theme/Admonition";
import Panel from "@site/src/components/Panel";
import Link from "@docusaurus/Link";
-
-
-
-
# Adding new guides
This template explains how to create new Guides.
@@ -56,7 +52,7 @@ Intro paragraph...
**Fields explained**
- `title` – main page title displayed in the header.
-- `publishedAt` – publication date (YYYY-MM-DD format). Displayed in the article header.
+- `published_at` – publication date (YYYY-MM-DD format). Displayed in the article header.
- `author` – name of the guide author (single author only). Displayed in the article header below the title. Must match exactly with a key in `docs/authors.json`.
- `tags` – keys from `guides/tags.yml` (see Tags). Displayed below the title.
- `image` – banner image displayed at the top of the article; can be a string or a themed image object (see Themed Images template). If not provided, a gradient background with icon is shown.
@@ -104,11 +100,11 @@ Use this pattern when the actual content lives elsewhere but you still want it l
```mdx
---
title: "Begin analysis with OLAP ETL"
-publishedAt: 2025-12-23
+published_at: 2025-12-23
author: "Author Name"
tags: [integration, getting-started]
description: "Short description shown in cards and lists."
-externalUrl: "https://ravendb.net/articles/begin-analysis-with-olap-etl"
+external_url: "https://ravendb.net/articles/begin-analysis-with-olap-etl"
image: "https://ravendb.net/wp-content/uploads/2025/12/OLAP-article-image.svg"
---
diff --git a/templates/new-samples.mdx b/templates/new-samples.mdx
new file mode 100644
index 0000000000..7c397d3294
--- /dev/null
+++ b/templates/new-samples.mdx
@@ -0,0 +1,192 @@
+---
+title: "Samples: Adding new samples"
+hide_table_of_contents: false
+sidebar_label: Adding new samples
+see_also:
+ - title: "Samples Introduction"
+ link: "/templates/introduction-samples"
+ source: "docs"
+ path: "Templates > Samples"
+ - title: "Sample tags"
+ link: "/templates/tags-samples"
+ source: "docs"
+ path: "Templates > Samples"
+ - title: "Sample components"
+ link: "/templates/components-samples"
+ source: "docs"
+ path: "Templates > Samples"
+---
+
+import Admonition from "@theme/Admonition";
+import Panel from "@site/src/components/Panel";
+import Link from "@docusaurus/Link";
+
+This guide explains how to create new sample pages in the Samples section.
+
+## Create the file
+
+Place the file under the `samples` directory:
+
+```
+samples/my-new-sample.mdx
+```
+
+## Frontmatter Schema
+
+
+
+```mdx
+---
+title: "My Sample Application"
+description: "A production-ready example demonstrating RavenDB features."
+challenges_solutions_tags: [semantic-search, integration-patterns]
+feature_tags: [vector-search, include, document-refresh]
+tech_stack_tags: [csharp, aspire, azure-functions]
+image: "/img/samples/my-sample/cover.webp"
+img_alt: "My Sample Application Screenshot"
+category: "Ecommerce"
+license: "MIT License"
+license_url: "https://opensource.org/licenses/MIT"
+repository_url: "https://github.com/ravendb/my-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: guide
+ subtitle: "Related Guide Title"
+ article_key: "guide-slug"
+ - type: documentation
+ documentation_type: docs
+ subtitle: "Vector Search Overview"
+ article_key: "ai-integration/vector-search/overview"
+---
+```
+
+
+
+### Frontmatter Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | ✅ | Sample name displayed in cards and page header |
+| `description` | `string` | ✅ | Short summary shown in sample cards |
+| `challenges_solutions_tags` | `string[]` | ✅ | Challenges & solutions tags from `samples/tags/challenges-solutions.yml` (kebab-case) |
+| `feature_tags` | `string[]` | ✅ | RavenDB feature tags from `samples/tags/feature.yml` (kebab-case) |
+| `tech_stack_tags` | `string[]` | ✅ | Technology tags from `samples/tags/tech-stack.yml` (kebab-case) |
+| `image` | `string` | ❌ | Cover image path (shown in sample cards) |
+| `img_alt` | `string` | ❌ | Alt text for the cover image |
+| `category` | `string` | ❌ | Business category (e.g., "Ecommerce", "Healthcare") - displayed in metadata sidebar |
+| `license` | `string` | ❌ | License type (e.g., "MIT License", "Apache 2.0") - displayed in metadata sidebar |
+| `license_url` | `string` | ❌ | License URL (e.g., `https://opensource.org/licenses/MIT`) - links the sidebar label and feeds JSON-LD |
+| `repository_url` | `string` | ❌ | GitHub repository URL - renders "Browse code" button; used in `SoftwareSourceCode` JSON-LD for SEO |
+| `demo_url` | `string` | ❌ | Live demo URL - renders "View demo" button in the sidebar |
+| `languages` | `string[]` | ❌ | Programming languages (e.g., `["C#"]`) - used in `SoftwareSourceCode` JSON-LD for SEO |
+| `gallery` | `array` | ❌ | Array of screenshot objects with `src` and `alt` properties |
+| `related_resources` | `array` | ❌ | Related guides and docs shown in the sidebar — see schema below |
+
+Each `related_resources` item accepts:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `type` | `"guide"` \| `"documentation"` | ✅ | Resource type |
+| `documentation_type` | `"docs"` \| `"cloud"` | ❌ | Documentation section (only for `type: documentation`) |
+| `subtitle` | `string` | ✅ | Display text |
+| `article_key` | `string` | ✅ | Article path without version prefix (e.g., `ai-integration/vector-search/overview`) |
+
+
+ All tag keys must exist in their respective YAML files (`samples/tags/challenges-solutions.yml`, `feature.yml`, `tech-stack.yml`). Using undefined tags will cause them to display with their raw key value instead of a formatted label.
+
+
+## Page Structure
+
+### Basic Layout
+
+
+
+```mdx
+---
+title: "My Sample"
+description: "Sample description"
+challenges_solutions_tags: [semantic-search]
+feature_tags: [vector-search]
+tech_stack_tags: [csharp]
+license: "MIT License"
+license_url: "https://opensource.org/licenses/MIT"
+repository_url: "https://github.com/ravendb/my-sample-repo"
+languages: ["C#"]
+related_resources:
+ - type: guide
+ subtitle: "Related Guide Title"
+ article_key: "guide-slug"
+ - type: documentation
+ documentation_type: docs
+ subtitle: "Vector Search Overview"
+ article_key: "ai-integration/vector-search/overview"
+---
+
+import { FeatureAccordion, SampleLayout } from '@site/src/components/Samples';
+
+
+
+## Overview
+
+Describe what the sample does and what problems it solves...
+
+## Features used
+
+
+ Detailed explanation of how vector search is used in this sample...
+
+ // Code example
+
+
+
+```
+
+
+
+
+ The `gallery` prop on `SampleLayout` provides optimal responsive behavior:
+
+ - **Mobile**: Gallery appears at the top, right after the page title and above the ActionsCard
+ - **Desktop**: Gallery appears in the main content area, before the Overview section
+
+ `SampleLayout` reads `gallery` from the `gallery` frontmatter field automatically. If the field is absent or empty, no gallery is rendered.
+
+
+
+ **Do NOT add a `#` heading in your markdown content.**
+
+ The `title` frontmatter is automatically rendered as the page heading. Adding a `#` heading breaks the layout.
+
+ ✅ Correct:
+ ```mdx
+ ---
+ title: "My Sample"
+ ---
+
+ ## Overview
+
+ Content starts here...
+ ```
+
+ ❌ Wrong:
+ ```mdx
+ ---
+ title: "My Sample"
+ ---
+
+ # My Sample
+
+ ## Overview
+ ```
+
+
diff --git a/templates/see-also.mdx b/templates/see-also.mdx
index 419a493843..ddce7cd89f 100644
--- a/templates/see-also.mdx
+++ b/templates/see-also.mdx
@@ -7,10 +7,6 @@ sidebar_label: See also
import Admonition from "@theme/Admonition";
import SeeAlso from "@site/src/components/SeeAlso";
-
-
-
-
# See also
The `SeeAlso` component is used to display a list of related articles or external resources at the end of a page. It is automatically rendered in the page footer when the `see_also` property is defined in the page's frontmatter.
diff --git a/templates/tags-samples.mdx b/templates/tags-samples.mdx
new file mode 100644
index 0000000000..5d9bfcf1fe
--- /dev/null
+++ b/templates/tags-samples.mdx
@@ -0,0 +1,176 @@
+---
+title: "Samples: Tags"
+hide_table_of_contents: false
+sidebar_label: Tags
+see_also:
+ - title: "Adding new samples"
+ link: "/templates/new-samples"
+ source: "docs"
+ path: "Templates > Samples"
+ - title: "Samples Introduction"
+ link: "/templates/introduction-samples"
+ source: "docs"
+ path: "Templates > Samples"
+---
+
+import Admonition from "@theme/Admonition";
+import Panel from "@site/src/components/Panel";
+
+Samples use a **three-category tag system** to enable powerful filtering and discovery. Unlike Guides which use a single flat tag list, Samples organize tags into separate category files.
+
+## Tag Categories
+
+### 1. Challenges & Solutions Tags (`samples/tags/challenges-solutions.yml`)
+
+These tags describe **what business problems** the sample solves.
+
+**Location:** `samples/tags/challenges-solutions.yml`
+
+**Some of the existing tags:**
+- `cloud-tax`
+- `gen-ai-data-enrichment`
+- `integration-patterns`
+- `semantic-search`
+
+**Example usage in frontmatter:**
+```yaml
+challenges_solutions_tags: [semantic-search, integration-patterns]
+```
+
+### 2. Feature Tags (`samples/tags/feature.yml`)
+
+These tags indicate **which RavenDB features** are demonstrated.
+
+**Location:** `samples/tags/feature.yml`
+
+**Some of the existing tags:**
+- `vector-search`
+- `document-refresh`
+- `include`
+- `azure-storage-queues-etl`
+- `ai-agents`
+- `full-text-search`
+
+**Example usage in frontmatter:**
+```yaml
+feature_tags: [vector-search, include, document-refresh]
+```
+
+### 3. Tech Stack Tags (`samples/tags/tech-stack.yml`)
+
+These tags specify **technologies and frameworks** used in the sample.
+
+**Location:** `samples/tags/tech-stack.yml`
+
+**Some of the existing tags:**
+- `csharp`
+- `nodejs`
+- `python`
+- `java`
+- `php`
+- `aspire`
+- `azure-storage-queues`
+- `azure-functions`
+
+**Example usage in frontmatter:**
+```yaml
+tech_stack_tags: [csharp, aspire, azure-functions]
+```
+
+## Adding New Tags
+
+### Step 1: Choose the correct category
+
+Determine which category your tag belongs to:
+- **Challenges & Solutions** - Business problem or use case
+- **Feature** - RavenDB feature or capability
+- **Tech Stack** - Programming language, framework, or service
+
+### Step 2: Edit the appropriate YAML file
+
+
+
+Edit `samples/tags/challenges-solutions.yml`:
+
+```yaml
+cloud-tax:
+ label: "Cloud Tax"
+gen-ai-data-enrichment:
+ label: "Gen AI Data Enrichment"
+# Add your new tag:
+real-time-analytics:
+ label: "Real-Time Analytics"
+```
+
+
+
+
+
+Edit `samples/tags/feature.yml`:
+
+```yaml
+vector-search:
+ label: "Vector Search"
+document-refresh:
+ label: "Document Refresh"
+# Add your new tag:
+time-series:
+ label: "Time Series"
+```
+
+
+
+
+
+Edit `samples/tags/tech-stack.yml`:
+
+```yaml
+csharp:
+ label: "C#"
+nodejs:
+ label: "Node.js"
+# Add your new tag:
+nextjs:
+ label: "Next.js"
+```
+
+
+
+### Step 3: Use the tag in a sample
+
+Reference the tag key in your sample's frontmatter:
+
+```mdx
+---
+title: "My Sample"
+challenges_solutions_tags: [real-time-analytics]
+feature_tags: [time-series]
+tech_stack_tags: [nextjs]
+---
+```
+
+
+ Each tag entry requires only a `label` field. The key (e.g., `cloud-tax`) is used in frontmatter, while the label (e.g., "Cloud Tax") is displayed in the UI.
+
+
+## Tag Guidelines
+
+
+ - **Be specific**: Use `azure-storage-queues-etl` instead of just `etl`
+ - **Use kebab-case**: `gen-ai-data-enrichment` not `GenAIDataEnrichment`
+ - **Keep labels concise**: "Vector Search" not "Vector Search Functionality"
+ - **Avoid duplicates**: Check existing tags before adding new ones
+ - **Stay consistent**: Follow naming patterns of existing tags
+
+
+
+ The following tech stack tags are treated specially as "language tags" and displayed with colored badges:
+ - `csharp`
+ - `java`
+ - `python`
+ - `php`
+ - `nodejs`
+
+ These should only be used for the primary programming language of the sample.
+
+
diff --git a/templates/tags.mdx b/templates/tags.mdx
index 6f40e217b9..7853b2c5a2 100644
--- a/templates/tags.mdx
+++ b/templates/tags.mdx
@@ -16,10 +16,6 @@ see_also:
import Admonition from "@theme/Admonition";
import Panel from "@site/src/components/Panel";
-
-
-
-
# Tags
## Add a new tag
diff --git a/templates/themed-images.mdx b/templates/themed-images.mdx
index 407d00bcbb..ae6b63c977 100644
--- a/templates/themed-images.mdx
+++ b/templates/themed-images.mdx
@@ -12,10 +12,6 @@ import ColGrid from "@site/src/components/ColGrid";
import lightImage from '@site/static/img/templates/light-image.png';
import darkImage from '@site/static/img/templates/dark-image.png';
-
-
-
-
# Themed Images overview
This guide shows how to use `ThemedImage` component to display different images for light and dark themes, ensuring optimal visual appearance in both modes.
@@ -30,7 +26,7 @@ import ThemedImage from '@theme/ThemedImage';
### Basic usage
-````mdx
+```mdx
import ThemedImage from '@theme/ThemedImage';
import lightImage from '@site/static/img/templates/light-image.png';
import darkImage from '@site/static/img/templates/dark-image.png';
@@ -42,7 +38,7 @@ import darkImage from '@site/static/img/templates/dark-image.png';
dark: darkImage,
}}
/>
-````
+```
#### Live example
@@ -98,96 +94,7 @@ import darkImage from '@site/static/img/templates/dark-image.png';
/>
```
-## Using ThemedImage in Card components
-Both `CardWithImage` and `CardWithImageHorizontal` support themed images by passing an object with `light` and `dark` properties to the `imgSrc` prop.
-
-### CardWithImage with themed images
-
-```mdx
-import CardWithImage from "@site/src/components/Common/CardWithImage";
-import lightImage from '@site/static/img/templates/light-image.png';
-import darkImage from '@site/static/img/templates/dark-image.png';
-
-
-
-
-### CardWithImageHorizontal with themed images
-
-```mdx
-import CardWithImageHorizontal from "@site/src/components/Common/CardWithImageHorizontal";
-import lightImage from '@site/static/img/templates/light-image.png';
-import darkImage from '@site/static/img/templates/dark-image.png';
-
-
-
-
-### Fallback to single image
-
-Both card components maintain backward compatibility. If you pass a string instead of an object, they'll use a regular `![]()
` tag:
-
-```mdx
-
-
## Best practices
@@ -197,9 +104,6 @@ Both card components maintain backward compatibility. If you pass a string inste
- **Optimize images**: Use appropriate image formats and compression for web performance.
- **Test both themes**: Verify that images look good in both light and dark modes.
-
-When using themed images in card components, the component automatically detects the object format and renders the appropriate image component. For single images, use a string; for themed images, use an object with `light` and `dark` properties.
-
## Props
@@ -214,12 +118,3 @@ When using themed images in card components, the component automatically detects
| height | number \| string | — | Image height (optional). |
| style | React.CSSProperties | — | Inline styles for the image (optional). |
-### CardWithImage / CardWithImageHorizontal
-
-The `imgSrc` prop accepts either:
-
-- **String**: Single image URL (backward compatible)
-- **Object**: `{ light: string; dark: string }` for themed images
-
-When an object is provided, the component automatically uses `ThemedImage` internally.
-
diff --git a/versioned_docs/version-1.0/home.mdx b/versioned_docs/version-1.0/home.mdx
index 614ef33eea..0c34d76a6f 100644
--- a/versioned_docs/version-1.0/home.mdx
+++ b/versioned_docs/version-1.0/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-2.0/home.mdx b/versioned_docs/version-2.0/home.mdx
index 614ef33eea..0c34d76a6f 100644
--- a/versioned_docs/version-2.0/home.mdx
+++ b/versioned_docs/version-2.0/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-2.5/home.mdx b/versioned_docs/version-2.5/home.mdx
index 614ef33eea..0c34d76a6f 100644
--- a/versioned_docs/version-2.5/home.mdx
+++ b/versioned_docs/version-2.5/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-3.0/home.mdx b/versioned_docs/version-3.0/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-3.0/home.mdx
+++ b/versioned_docs/version-3.0/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-3.5/home.mdx b/versioned_docs/version-3.5/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-3.5/home.mdx
+++ b/versioned_docs/version-3.5/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-4.0/home.mdx b/versioned_docs/version-4.0/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-4.0/home.mdx
+++ b/versioned_docs/version-4.0/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-4.1/home.mdx b/versioned_docs/version-4.1/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-4.1/home.mdx
+++ b/versioned_docs/version-4.1/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-4.2/home.mdx b/versioned_docs/version-4.2/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-4.2/home.mdx
+++ b/versioned_docs/version-4.2/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-5.0/home.mdx b/versioned_docs/version-5.0/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-5.0/home.mdx
+++ b/versioned_docs/version-5.0/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-5.1/home.mdx b/versioned_docs/version-5.1/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-5.1/home.mdx
+++ b/versioned_docs/version-5.1/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-5.2/home.mdx b/versioned_docs/version-5.2/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-5.2/home.mdx
+++ b/versioned_docs/version-5.2/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-5.3/home.mdx b/versioned_docs/version-5.3/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-5.3/home.mdx
+++ b/versioned_docs/version-5.3/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-5.4/home.mdx b/versioned_docs/version-5.4/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-5.4/home.mdx
+++ b/versioned_docs/version-5.4/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-6.0/home.mdx b/versioned_docs/version-6.0/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-6.0/home.mdx
+++ b/versioned_docs/version-6.0/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-6.2/home.mdx b/versioned_docs/version-6.2/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-6.2/home.mdx
+++ b/versioned_docs/version-6.2/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-7.0/home.mdx b/versioned_docs/version-7.0/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-7.0/home.mdx
+++ b/versioned_docs/version-7.0/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---
diff --git a/versioned_docs/version-7.1/home.mdx b/versioned_docs/version-7.1/home.mdx
index f694bf8226..a1935c0184 100644
--- a/versioned_docs/version-7.1/home.mdx
+++ b/versioned_docs/version-7.1/home.mdx
@@ -2,7 +2,7 @@
slug: /
pagination_next: null
pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
hide_table_of_contents: true
---