feat: add isDraft property and feature flags for content visibility

Add lightweight feature flag system (SHOW_DRAFTS, EXAMPLES_FEATURE) to
control content visibility across the site. Recipes, templates, and
examples now support an optional isDraft property that hides them from
llms.txt, API markdown endpoints, and UI resource lists unless
SHOW_DRAFTS is enabled. The EXAMPLES_FEATURE flag gates all example
content (routes, filters, landing page carousel, llms.txt section).
Both flags default to disabled when unset.

Author: andrelandgraf

api/content-markdown.ts

@@ -6,10 +6,12 @@ import { hasMarkdownSlug } from "../src/lib/content-markdown";
 import { expandMdxImports } from "../src/lib/expand-mdx";
 import {
   examples,
+  filterPublished,
   recipes,
   recipesInOrder,
   templates,
 } from "../src/lib/recipes/recipes";
+import { showDrafts, examplesEnabled } from "../src/lib/feature-flags-server";
 import { solutions } from "../src/lib/solutions/solutions";
 
 export type MarkdownSection =
@@ -212,32 +214,40 @@ function readResourceMarkdown(rootDir: string, slug: string): string {
 
 /** Markdown index served at /resources.md — lists all templates, recipes, and examples. */
 function readResourcesIndex(): string {
+  const includeDrafts = showDrafts();
+  const includeExamples = examplesEnabled();
+  const publishedTemplates = filterPublished(templates, includeDrafts);
+  const publishedRecipes = filterPublished(recipesInOrder, includeDrafts);
+  const publishedExamples = includeExamples
+    ? filterPublished(examples, includeDrafts)
+    : [];
+
   const lines: string[] = [
     "# Resources",
     "",
     "Guides and examples for building on Databricks.",
     "",
   ];
 
-  if (templates.length > 0) {
+  if (publishedTemplates.length > 0) {
     lines.push("## Guides", "");
-    for (const t of templates) {
+    for (const t of publishedTemplates) {
       lines.push(`- [${t.name}](/resources/${t.id}.md): ${t.description}`);
     }
     lines.push("");
   }
 
-  if (recipesInOrder.length > 0) {
+  if (publishedRecipes.length > 0) {
     lines.push("## Recipes", "");
-    for (const r of recipesInOrder) {
+    for (const r of publishedRecipes) {
       lines.push(`- [${r.name}](/resources/${r.id}.md): ${r.description}`);
     }
     lines.push("");
   }
 
-  if (examples.length > 0) {
+  if (publishedExamples.length > 0) {
     lines.push("## Examples", "");
-    for (const e of examples) {
+    for (const e of publishedExamples) {
       lines.push(`- [${e.name}](/resources/${e.id}.md): ${e.description}`);
     }
     lines.push("");

docusaurus.config.ts

@@ -12,6 +12,13 @@ const config: Config = {
   title: "Databricks Developer",
   tagline: "Build intelligent data and AI applications in minutes, not months",
   favicon: "img/favicon.svg",
+  customFields: {
+    showDrafts:
+      process.env.SHOW_DRAFTS === "true" || process.env.SHOW_DRAFTS === "1",
+    examplesFeature:
+      process.env.EXAMPLES_FEATURE === "true" ||
+      process.env.EXAMPLES_FEATURE === "1",
+  },
 
   // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
   future: {

plugins/content-entries.ts

@@ -2,7 +2,13 @@ import { readFileSync } from "fs";
 import { resolve } from "path";
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import { getMarkdownSlugs } from "../src/lib/content-markdown";
-import { recipes, examples, templates } from "../src/lib/recipes/recipes";
+import {
+  recipes,
+  examples,
+  templates,
+  filterPublished,
+} from "../src/lib/recipes/recipes";
+import { showDrafts, examplesEnabled } from "../src/lib/feature-flags-server";
 import { solutions } from "../src/lib/solutions/solutions";
 
 function assertNoDuplicateSlugs(): void {
@@ -84,6 +90,22 @@ export default function ExampleEntryPage(): ReactNode {
 }
 
 function getRegistrySlugs(entryType: EntryType): string[] {
+  const includeDrafts = showDrafts();
+  if (entryType === "recipe") {
+    return filterPublished(recipes, includeDrafts)
+      .map((recipe) => recipe.id)
+      .sort();
+  }
+  if (entryType === "example") {
+    if (!examplesEnabled()) return [];
+    return filterPublished(examples, includeDrafts)
+      .map((example) => example.id)
+      .sort();
+  }
+  return solutions.map((solution) => solution.id).sort();
+}
+
+function getAllRegistrySlugs(entryType: EntryType): string[] {
   if (entryType === "recipe") {
     return recipes.map((recipe) => recipe.id).sort();
   }
@@ -93,15 +115,11 @@ function getRegistrySlugs(entryType: EntryType): string[] {
   return solutions.map((solution) => solution.id).sort();
 }
 
-function assertSlugParity(
-  entryType: EntryType,
-  contentSlugs: string[],
-  registrySlugs: string[],
-): void {
-  const onlyInContent = contentSlugs.filter(
-    (slug) => !registrySlugs.includes(slug),
-  );
-  const onlyInRegistry = registrySlugs.filter(
+function assertSlugParity(entryType: EntryType, contentSlugs: string[]): void {
+  const allSlugs = getAllRegistrySlugs(entryType);
+
+  const onlyInContent = contentSlugs.filter((slug) => !allSlugs.includes(slug));
+  const onlyInRegistry = allSlugs.filter(
     (slug) => !contentSlugs.includes(slug),
   );
 
@@ -135,11 +153,12 @@ export default function contentEntriesPlugin(
         context.siteDir,
         options.contentSection,
       );
-      const registrySlugs = getRegistrySlugs(options.entryType);
-      assertSlugParity(options.entryType, contentSlugs, registrySlugs);
+      assertSlugParity(options.entryType, contentSlugs);
+
+      const publishedSlugs = getRegistrySlugs(options.entryType);
 
       const rawMarkdownBySlug: Record<string, string> = {};
-      for (const slug of contentSlugs) {
+      for (const slug of publishedSlugs) {
         const filePath = resolve(
           context.siteDir,
           "content",
@@ -152,11 +171,11 @@ export default function contentEntriesPlugin(
       setGlobalData({
         entryType: options.entryType,
         routeBasePath: options.routeBasePath,
-        slugs: contentSlugs,
+        slugs: publishedSlugs,
         rawMarkdownBySlug,
       });
 
-      for (const slug of contentSlugs) {
+      for (const slug of publishedSlugs) {
         const modulePath = await createData(
           `${options.id}-${slug}-route.tsx`,
           createRouteModuleSource(options.entryType, slug),

plugins/llms-txt.ts

@@ -6,8 +6,10 @@ import {
   templates,
   recipesInOrder,
   examples,
+  filterPublished,
 } from "../src/lib/recipes/recipes";
 import { expandMdxImports } from "../src/lib/expand-mdx";
+import { showDrafts, examplesEnabled } from "../src/lib/feature-flags-server";
 
 type Section = {
   title: string;
@@ -136,6 +138,14 @@ function readDoc(
 }
 
 function generateLlmsTxt(baseUrl: string, docsDir: string): string {
+  const includeDrafts = showDrafts();
+  const includeExamples = examplesEnabled();
+  const publishedTemplates = filterPublished(templates, includeDrafts);
+  const publishedRecipes = filterPublished(recipesInOrder, includeDrafts);
+  const publishedExamples = includeExamples
+    ? filterPublished(examples, includeDrafts)
+    : [];
+
   const allSections: Section[] = SIDEBAR_SECTIONS.map((section) => ({
     title: section.title,
     description: section.description,
@@ -191,35 +201,35 @@ function generateLlmsTxt(baseUrl: string, docsDir: string): string {
     "",
   );
 
-  if (templates.length > 0) {
+  if (publishedTemplates.length > 0) {
     lines.push(
       "### Guides",
       "",
-      ...templates.map(
+      ...publishedTemplates.map(
         (t) =>
           `- [${t.name}](${baseUrl}/resources/${t.id}.md): ${t.description}`,
       ),
       "",
     );
   }
 
-  if (recipesInOrder.length > 0) {
+  if (publishedRecipes.length > 0) {
     lines.push(
       "### Recipes",
       "",
-      ...recipesInOrder.map(
+      ...publishedRecipes.map(
         (r) =>
           `- [${r.name}](${baseUrl}/resources/${r.id}.md): ${r.description}`,
       ),
       "",
     );
   }
 
-  if (examples.length > 0) {
+  if (publishedExamples.length > 0) {
     lines.push(
       "### Examples",
       "",
-      ...examples.map(
+      ...publishedExamples.map(
         (e) =>
           `- [${e.name}](${baseUrl}/resources/${e.id}.md): ${e.description}`,
       ),

src/components/home/template-preview.tsx

@@ -15,8 +15,9 @@ import {
   CarouselPrevious,
   CarouselNext,
 } from "@/components/ui/carousel";
+import { useFeatureFlags } from "@/lib/feature-flags";
 import {
-  landingResources,
+  buildLandingResources,
   type LandingResourceItem,
 } from "@/lib/landing-content";
 
@@ -171,13 +172,20 @@ function ResourceCard({
 }
 
 export function TemplatePreview(): ReactNode {
+  const { showDrafts: includeDrafts, examplesEnabled: includeExamples } =
+    useFeatureFlags();
+  const landingResources = buildLandingResources(
+    includeDrafts,
+    includeExamples,
+  );
+
   return (
     <section className="bg-white py-16 dark:bg-db-navy md:py-20">
       <div className="container px-4">
         <div className="mx-auto mb-8 max-w-6xl">
           <p className="mb-3 inline-flex items-center gap-2 text-[10px] font-semibold tracking-[0.12em] text-black/50 uppercase dark:text-white/50">
             <span className="text-db-lava">&#9679;</span>
-            Guides and Examples
+            {includeExamples ? "Guides and Examples" : "Guides"}
           </p>
           <div className="flex flex-col gap-3 md:flex-row md:items-end md:justify-between">
             <h2 className="max-w-xl text-3xl leading-tight font-medium tracking-tight text-black dark:text-white md:text-4xl">

src/components/resources/resource-filters.tsx

@@ -1,8 +1,17 @@
 import { Checkbox } from "@/components/ui/checkbox";
+import { useFeatureFlags } from "@/lib/feature-flags";
 import { SERVICES, type Service } from "@/lib/recipes/recipes";
 
 export type ResourceType = "examples" | "guides";
 
+const ALL_RESOURCE_TYPES: ReadonlyArray<{
+  type: ResourceType;
+  label: string;
+}> = [
+  { type: "examples", label: "Examples" },
+  { type: "guides", label: "Guides" },
+];
+
 export function ResourceFilters({
   selectedServices,
   onToggleService,
@@ -14,6 +23,12 @@ export function ResourceFilters({
   selectedResourceTypes: Set<ResourceType>;
   onToggleResourceType: (type: ResourceType) => void;
 }) {
+  const { examplesEnabled } = useFeatureFlags();
+
+  const visibleResourceTypes = examplesEnabled
+    ? ALL_RESOURCE_TYPES
+    : ALL_RESOURCE_TYPES.filter((rt) => rt.type !== "examples");
+
   return (
     <nav className="space-y-6" aria-label="Filters">
       <div>
@@ -37,31 +52,28 @@ export function ResourceFilters({
         </div>
       </div>
 
-      <div className="border-t border-black/8 pt-6 dark:border-white/8">
-        <h3 className="mb-3 text-xs font-semibold tracking-wider text-black/50 uppercase dark:text-white/50">
-          Type
-        </h3>
-        <div className="space-y-2">
-          {(
-            [
-              { type: "examples" as const, label: "Examples" },
-              { type: "guides" as const, label: "Guides" },
-            ] as const
-          ).map(({ type, label }) => (
-            <label
-              key={type}
-              className="flex cursor-pointer items-center gap-2.5 rounded-md px-1 py-1 text-sm text-black/80 transition-colors hover:bg-black/4 dark:text-white/80 dark:hover:bg-white/4"
-            >
-              <Checkbox
-                checked={selectedResourceTypes.has(type)}
-                onCheckedChange={() => onToggleResourceType(type)}
-                aria-label={label}
-              />
-              <span className="leading-tight">{label}</span>
-            </label>
-          ))}
+      {visibleResourceTypes.length > 1 && (
+        <div className="border-t border-black/8 pt-6 dark:border-white/8">
+          <h3 className="mb-3 text-xs font-semibold tracking-wider text-black/50 uppercase dark:text-white/50">
+            Type
+          </h3>
+          <div className="space-y-2">
+            {visibleResourceTypes.map(({ type, label }) => (
+              <label
+                key={type}
+                className="flex cursor-pointer items-center gap-2.5 rounded-md px-1 py-1 text-sm text-black/80 transition-colors hover:bg-black/4 dark:text-white/80 dark:hover:bg-white/4"
+              >
+                <Checkbox
+                  checked={selectedResourceTypes.has(type)}
+                  onCheckedChange={() => onToggleResourceType(type)}
+                  aria-label={label}
+                />
+                <span className="leading-tight">{label}</span>
+              </label>
+            ))}
+          </div>
         </div>
-      </div>
+      )}
     </nav>
   );
 }

src/lib/feature-flags-server.ts

@@ -0,0 +1,9 @@
+export function showDrafts(): boolean {
+  const value = process.env.SHOW_DRAFTS;
+  return value === "true" || value === "1";
+}
+
+export function examplesEnabled(): boolean {
+  const value = process.env.EXAMPLES_FEATURE;
+  return value === "true" || value === "1";
+}

src/lib/feature-flags.ts

@@ -0,0 +1,10 @@
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+
+export function useFeatureFlags() {
+  const { siteConfig } = useDocusaurusContext();
+  const fields = siteConfig.customFields as Record<string, unknown>;
+  return {
+    showDrafts: fields.showDrafts === true,
+    examplesEnabled: fields.examplesFeature === true,
+  };
+}