docs: add examples

docs/.docs/components/Sandbox.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+const props = defineProps<{
+  src?: string
+  repo?: string
+  branch?: string
+  dir?: string
+  file?: string
+}>()
+
+const colorMode = useColorMode()
+
+const url = computed(() => {
+  if (props.src) {
+    return props.src
+  }
+  const base = `https://stackblitz.com/github/${props.repo}/tree/${props.branch || 'main'}/${props.dir || ''}`
+  const params = new URLSearchParams({
+    embed: '1',
+    file: props.file || 'README.md',
+    theme: colorMode.value,
+  })
+  return `${base}?${params.toString()}`
+})
+</script>
+
+<template>
+  <div class="w-full min-h-[500px] mx-auto overflow-hidden rounded-md mt-4 border border-default">
+    <iframe
+      v-if="url"
+      :src="url"
+      title="StackBlitz Sandbox"
+      sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
+      class="w-full h-full min-h-[600px] overflow-hidden bg-gray-100 dark:bg-gray-800"
+    />
+    <div v-else class="flex items-center justify-center h-[600px] text-muted">
+      Loading Sandbox...
+    </div>
+  </div>
+</template>

docs/.docs/content.config.ts

@@ -0,0 +1,20 @@
+import { defineContentConfig, defineCollection, z } from '@nuxt/content'
+import { resolve } from 'pathe'
+
+export default defineContentConfig({
+  collections: {
+    examples: defineCollection({
+      type: 'page',
+      source: {
+        cwd: resolve(__dirname, '../../examples'),
+        include: '**/README.md',
+        prefix: '/examples',
+        exclude: ['**/.**/**', '**/node_modules/**', '**/dist/**', '**/.docs/**'],
+      },
+      schema: z.object({
+        category: z.string().optional(),
+        icon: z.string().optional(),
+      }),
+    }),
+  },
+})

docs/.docs/layouts/examples.vue

@@ -0,0 +1,85 @@
+<script setup lang="ts">
+import type { ContentNavigationItem } from '@nuxt/content'
+import { categoryOrder } from '~/utils/examples'
+
+// Fetch all examples and group by category
+const { data: examples } = await useAsyncData('examples-nav', () =>
+  queryCollection('examples')
+    .select('title', 'description', 'category', 'path')
+    .all(),
+)
+
+// Group examples by category
+const groupedExamples = computed(() => {
+  if (!examples.value) return []
+
+  const groups: Record<string, ContentNavigationItem[]> = {}
+
+  for (const example of examples.value) {
+    const category = example.category || 'Other'
+    if (!groups[category]) {
+      groups[category] = []
+    }
+    groups[category].push({
+      title: example.title,
+      path: example.path.replace(/\/readme$/i, ''),
+    })
+  }
+
+  // Convert to navigation items with children, sorted by categoryOrder
+  const sortedEntries = Object.entries(groups).sort(([a], [b]) => {
+    const aIndex = categoryOrder.indexOf(a.toLowerCase())
+    const bIndex = categoryOrder.indexOf(b.toLowerCase())
+    if (aIndex === -1 && bIndex === -1) return a.localeCompare(b)
+    if (aIndex === -1) return 1
+    if (bIndex === -1) return -1
+    return aIndex - bIndex
+  })
+
+  return sortedEntries.map(([category, items]) => ({
+    title: category.split(' ').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' '),
+    path: '',
+    children: items,
+  }))
+})
+
+// Flat list for navigation (no groups)
+const flatExamples = computed(() => {
+  if (!examples.value) return []
+  return examples.value.map((example) => ({
+    title: example.title,
+    path: example.path.replace(/\/readme$/i, ''),
+  }))
+})
+</script>
+
+<template>
+  <UContainer>
+    <UPage :ui="{ left: 'lg:col-span-2 pr-2 border-r border-default' }">
+      <template #left>
+        <UPageAside>
+          <UPageAnchors
+            :links="[
+              { label: 'Docs', icon: 'i-lucide-book-open', to: '/docs' },
+              { label: 'Deploy', icon: 'ri:upload-cloud-2-line', to: '/deploy' },
+              { label: 'Config', icon: 'ri:settings-3-line', to: '/config' },
+              { label: 'Examples', icon: 'i-lucide-folder-code', to: '/examples', active: true },
+            ]"
+          />
+          <USeparator type="dashed" class="py-6" />
+          <UContentNavigation
+            v-if="groupedExamples.length"
+            :navigation="groupedExamples"
+            :collapsible="false"
+          />
+          <UContentNavigation
+            v-else-if="flatExamples.length"
+            :navigation="flatExamples"
+            :collapsible="false"
+          />
+        </UPageAside>
+      </template>
+      <slot />
+    </UPage>
+  </UContainer>
+</template>

docs/.docs/pages/examples/[...slug].vue

@@ -0,0 +1,122 @@
+<script setup lang="ts">
+import { joinURL } from 'ufo'
+import { kebabCase } from 'scule'
+
+definePageMeta({
+  layout: 'examples',
+})
+
+const appConfig = useAppConfig()
+const route = useRoute()
+
+const { data: page } = await useAsyncData(kebabCase(route.path), () =>
+  queryCollection('examples').path(`${route.path}/readme`).first(),
+)
+if (!page.value) {
+  throw createError({
+    statusCode: 404,
+    statusMessage: 'Example not found',
+    message: `${route.path} does not exist`,
+    fatal: true,
+  })
+}
+
+const { data: surround } = await useAsyncData(`${kebabCase(route.path)}-surround`, () => {
+  return queryCollectionItemSurroundings('examples', `${route.path}/readme`, {
+    fields: ['description'],
+  })
+})
+
+// Extract example name from route (e.g., "/examples/vite-ssr-html" -> "vite-ssr-html")
+const exampleName = computed(() => {
+  return route.path.replace(/^\/examples\//, '')
+})
+
+const breadcrumb = computed(() => [
+  { label: 'Examples', icon: 'i-lucide-folder-code', to: '/examples' },
+  { label: page.value?.title || exampleName.value },
+])
+
+usePageSEO({
+  title: `${page.value?.title} - ${appConfig.site.name}`,
+  ogTitle: page.value?.title,
+  description: page.value?.description,
+})
+
+const path = computed(() => route.path.replace(/\/$/, ''))
+prerenderRoutes([joinURL('/raw', `${path.value}.md`)])
+useHead({
+  link: [
+    {
+      rel: 'alternate',
+      href: joinURL(appConfig.site.url, 'raw', `${path.value}.md`),
+      type: 'text/markdown',
+    },
+  ],
+})
+</script>
+
+<template>
+  <UPage v-if="page">
+    <UPageHeader
+      :title="page.title"
+      :description="page.description"
+      :ui="{
+        wrapper: 'flex-row items-center flex-wrap justify-between',
+      }"
+    >
+      <template #headline>
+        <UBreadcrumb :items="breadcrumb" />
+      </template>
+      <template #links>
+        <UButton
+          icon="i-simple-icons-stackblitz"
+          label="Open in Playground"
+          color="neutral"
+          variant="soft"
+          size="sm"
+          :to="`https://stackblitz.com/fork/github/${appConfig.docs.github}/tree/${appConfig.docs.branch || 'main'}/examples/${exampleName}`"
+          target="_blank"
+        />
+
+        <UButton
+          icon="i-simple-icons-github"
+          label="Source"
+          color="neutral"
+          variant="soft"
+          size="sm"
+          :to="`https://github.com/${appConfig.docs.github}/tree/${appConfig.docs.branch || 'main'}/examples/${exampleName}`"
+          target="_blank"
+        />
+
+        <PageHeaderLinks />
+      </template>
+    </UPageHeader>
+
+    <template v-if="page.body?.toc?.links?.length" #right>
+      <UContentToc title="On this page" :links="page.body?.toc?.links || []" highlight />
+    </template>
+
+    <UPageBody prose class="break-words">
+      <ContentRenderer v-if="page.body" :value="page" />
+
+      <div class="space-y-6">
+        <USeparator type="dashed" />
+        <div class="mb-4">
+          <UPageLinks
+            class="inline-block"
+            :links="[
+              {
+                icon: 'i-lucide-pencil',
+                label: 'Edit this page',
+                to: `https://github.com/${appConfig.docs.github}/edit/${appConfig.docs.branch || 'main'}/examples/${exampleName}/README.md`,
+                target: '_blank',
+              },
+            ]"
+          />
+        </div>
+        <UContentSurround v-if="surround?.length" class="mb-4" :surround="surround" />
+      </div>
+    </UPageBody>
+  </UPage>
+</template>

docs/.docs/pages/examples/index.vue

@@ -0,0 +1,96 @@
+<script setup lang="ts">
+import { categoryOrder, categoryIcons } from '~/utils/examples'
+
+definePageMeta({
+  layout: 'examples',
+})
+
+const appConfig = useAppConfig()
+
+// Fetch all examples
+const { data: examples } = await useAsyncData('examples-list', () =>
+  queryCollection('examples')
+    .select('title', 'description', 'category', 'path', 'icon')
+    .all(),
+)
+
+// Group examples by category
+const groupedExamples = computed(() => {
+  if (!examples.value) return {}
+
+  const groups: Record<string, typeof examples.value> = {}
+
+  for (const example of examples.value) {
+    const category = example.category || 'Other'
+    if (!groups[category]) {
+      groups[category] = []
+    }
+    groups[category].push(example)
+  }
+
+  // Sort groups by categoryOrder
+  const sortedEntries = Object.entries(groups).sort(([a], [b]) => {
+    const aIndex = categoryOrder.indexOf(a.toLowerCase())
+    const bIndex = categoryOrder.indexOf(b.toLowerCase())
+    if (aIndex === -1 && bIndex === -1) return a.localeCompare(b)
+    if (aIndex === -1) return 1
+    if (bIndex === -1) return -1
+    return aIndex - bIndex
+  })
+
+  return Object.fromEntries(sortedEntries)
+})
+
+usePageSEO({
+  title: `Examples - ${appConfig.site.name}`,
+  ogTitle: 'Examples',
+  description: 'Explore Nitro examples to learn how to build full-stack applications',
+})
+</script>
+
+<template>
+  <UPage>
+    <UPageHeader
+      title="Examples"
+      description="Explore Nitro examples to learn how to build full-stack applications with different frameworks and features."
+    >
+      <template #headline>
+        <UBreadcrumb :items="[{ label: 'Examples', icon: 'i-lucide-code' }]" />
+      </template>
+    </UPageHeader>
+
+    <UPageBody>
+      <UAlert
+        color="warning"
+        variant="subtle"
+        icon="i-lucide-triangle-alert"
+        title="Work in Progress"
+        description="Nitro v3 Alpha docs and examples are a work in progress — expect updates, rough edges, and occasional inaccuracies."
+        class="mb-8"
+      />
+
+      <div v-for="(categoryExamples, category) in groupedExamples" :key="category" class="mb-12">
+        <h2 class="text-xl font-semibold mb-4 flex items-center gap-2">
+          <UIcon :name="categoryIcons[String(category).toLowerCase()] || categoryIcons.other" class="size-5" />
+          {{ String(category).charAt(0).toUpperCase() + String(category).slice(1) }}
+        </h2>
+
+        <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+          <UPageCard
+            v-for="example in categoryExamples"
+            :key="example.path"
+            :to="example.path.replace(/\/readme$/i, '')"
+            :title="example.title"
+            :description="example.description"
+            :icon="example.icon"
+          />
+        </div>
+      </div>
+
+      <div v-if="!examples?.length" class="text-center py-12">
+        <UIcon name="i-lucide-book-dashed" class="size-12 text-muted mx-auto mb-4" />
+        <p class="text-muted">No examples</p>
+      </div>
+    </UPageBody>
+  </UPage>
+</template>

docs/.docs/server/routes/raw/examples/[...slug].md.get.ts

@@ -0,0 +1,28 @@
+import { queryCollection } from '@nuxt/content/server'
+import { stringify } from 'minimark/stringify'
+import { withLeadingSlash } from 'ufo'
+
+export default eventHandler(async (event) => {
+  const slug = getRouterParams(event)['slug.md']
+  if (!slug?.endsWith('.md')) {
+    throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
+  }
+
+  // Convert /raw/examples/hello-world.md -> /examples/hello-world/readme
+  const exampleName = slug.replace('.md', '')
+  const path = withLeadingSlash(`examples/${exampleName}/readme`)
+
+  const page = await queryCollection(event, 'examples').path(path).first()
+  if (!page) {
+    throw createError({ statusCode: 404, statusMessage: 'Example not found', fatal: true })
+  }
+
+  // Add title and description to the top of the page if missing
+  if (page.body.value[0]?.[0] !== 'h1') {
+    page.body.value.unshift(['blockquote', {}, page.description])
+    page.body.value.unshift(['h1', {}, page.title])
+  }
+
+  setHeader(event, 'Content-Type', 'text/markdown; charset=utf-8')
+  return stringify({ ...page.body, type: 'minimark' }, { format: 'markdown/html' })
+})