feat: social share card meta (og/twitter)

README.md

@@ -109,7 +109,7 @@ pnpm check          # lint + 类型检查 + token 契约检查
 
 ## 文档站
 
-https://ui-a09.pages.dev
+https://ui.froq.me
 
 `docs/` 用 Nuxt Content。静态产物在仓库根目录的 `dist/`。部署到 Cloudflare Workers（Worker 名 `ui`）：Workers Builds 连本仓库，生产分支 `main`，环境变量 `NODE_VERSION=22`，构建命令 `pnpm generate`，生产部署 `pnpm exec cf deploy`，非生产预览 `pnpm exec cf previews deploy`。
 

docs/app/composables/useShareMeta.ts

@@ -0,0 +1,30 @@
+import type { MaybeRefOrGetter } from 'vue'
+import { canonicalUrl, shareTitle } from '../../shared/site'
+
+/** Document title plus Open Graph / Twitter tags for the current route. */
+export function useShareMeta(input: {
+  title?: MaybeRefOrGetter<string | undefined>
+  description?: MaybeRefOrGetter<string | undefined>
+  type?: MaybeRefOrGetter<'website' | 'article' | undefined>
+} = {}): void {
+  const route = useRoute()
+  const title = computed(() => shareTitle(toValue(input.title)))
+  const description = computed(() => {
+    const value = input.description == null ? undefined : toValue(input.description)
+    return value || undefined
+  })
+
+  useHead({
+    title: () => input.title == null ? undefined : toValue(input.title) || undefined,
+  })
+
+  useSeoMeta({
+    description,
+    ogTitle: title,
+    twitterTitle: title,
+    ogDescription: description,
+    twitterDescription: description,
+    ogUrl: () => canonicalUrl(route.path),
+    ogType: () => toValue(input.type) ?? 'website',
+  })
+}

docs/app/error.vue

@@ -1,12 +1,15 @@
 <script setup lang="ts">
 import type { NuxtError } from '#app'
 
-defineProps<{ error: NuxtError }>()
+const props = defineProps<{ error: NuxtError }>()
 
 const { t } = useI18n()
 const link = useSiteLink()
 
-useHead({ title: () => t('notFound.title') })
+useShareMeta({
+  title: () => t('notFound.title'),
+  description: () => props.error.statusMessage || props.error.message,
+})
 </script>
 
 <template>

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

@@ -16,8 +16,11 @@ const { data: page } = await useAsyncData(
 if (!page.value)
   throw createError({ statusCode: 404, statusMessage: 'Not found', fatal: true })
 
-useHead(() => ({ title: page.value?.title || undefined }))
-useSeoMeta({ description: () => page.value?.description })
+useShareMeta({
+  title: () => page.value?.title,
+  description: () => page.value?.description,
+  type: 'article',
+})
 </script>
 
 <template>

docs/app/pages/changelog.vue

@@ -7,8 +7,10 @@ const { data: releases } = await useAsyncData(
   () => queryCollection('changelog').where('path', 'LIKE', `${contentPath('/changelog')}/%`).order('date', 'DESC').all(),
 )
 
-useHead({ title: () => t('changelog.title') })
-useSeoMeta({ description: () => t('changelog.lede') })
+useShareMeta({
+  title: () => t('changelog.title'),
+  description: () => t('changelog.lede'),
+})
 </script>
 
 <template>

docs/app/pages/components/[concept]/[name].vue

@@ -10,8 +10,10 @@ if (!concept.value || !item.value)
 
 const hasApi = computed(() => Boolean(doc.value?.model || doc.value?.props?.length || doc.value?.slots?.length || doc.value?.events?.length))
 
-useHead({ title: () => item.value?.name })
-useSeoMeta({ description: () => doc.value?.description })
+useShareMeta({
+  title: () => item.value?.name,
+  description: () => doc.value?.description,
+})
 </script>
 
 <template>

docs/app/pages/components/[concept]/index.vue

@@ -7,7 +7,10 @@ const { docFor } = await useComponentDocs()
 if (!concept.value)
   throw createError({ statusCode: 404, statusMessage: 'Not found', fatal: true })
 
-useHead({ title: () => concept.value?.id })
+useShareMeta({
+  title: () => concept.value?.id,
+  description: () => concept.value?.items.map(item => item.name).join(', '),
+})
 </script>
 
 <template>

docs/app/pages/components/index.vue

@@ -3,7 +3,10 @@ const { t } = useI18n()
 const link = useSiteLink()
 const sections = componentSections()
 
-useHead({ title: () => t('components.title') })
+useShareMeta({
+  title: () => t('components.title'),
+  description: () => t('components.lede'),
+})
 
 const { docFor } = await useComponentDocs()
 

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

@@ -73,8 +73,11 @@ const index = computed(() => pages.value.findIndex(item => item.to === herePath.
 const prev = computed(() => pages.value[index.value - 1])
 const next = computed(() => pages.value[index.value + 1])
 
-useHead({ title: () => doc.value?.title })
-useSeoMeta({ description: () => doc.value?.description })
+useShareMeta({
+  title: () => doc.value?.title,
+  description: () => doc.value?.description,
+  type: 'article',
+})
 </script>
 
 <template>

docs/app/pages/index.vue

@@ -9,8 +9,10 @@ const catalog = componentCatalog()
 const count = catalog.reduce((total, concept) => total + concept.items.length, 0)
 const options = computed(() => ['quiet', 'clear', 'loud'].map(value => ({ value, label: t(`hero.${value}`) })))
 
-useHead({ title: 'froq/ui' })
-useSeoMeta({ description: () => t('hero.lede') })
+useShareMeta({
+  title: 'froq/ui',
+  description: () => t('hero.lede'),
+})
 </script>
 
 <template>

docs/nuxt.config.ts

@@ -1,6 +1,7 @@
 import { readdirSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { componentFile } from './shared/component-files'
+import { OG_IMAGE_URL, SITE_DESCRIPTION, SITE_NAME, SITE_ORIGIN } from './shared/site'
 
 const siteDist = fileURLToPath(new URL('../dist', import.meta.url))
 const componentsRoot = fileURLToPath(new URL('../src/components', import.meta.url))
@@ -41,7 +42,26 @@ export default defineNuxtConfig({
     pageTransition: { name: 'page', mode: 'out-in' },
     head: {
       link: [{ rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }],
-      meta: [{ name: 'color-scheme', content: 'light dark' }],
+      meta: [
+        { name: 'color-scheme', content: 'light dark' },
+        { name: 'description', content: SITE_DESCRIPTION },
+        { name: 'twitter:card', content: 'summary_large_image' },
+        { name: 'twitter:title', content: SITE_NAME },
+        { name: 'twitter:description', content: SITE_DESCRIPTION },
+        { name: 'twitter:image', content: OG_IMAGE_URL },
+        { name: 'twitter:image:alt', content: SITE_NAME },
+        { property: 'og:site_name', content: SITE_NAME },
+        { property: 'og:type', content: 'website' },
+        { property: 'og:title', content: SITE_NAME },
+        { property: 'og:description', content: SITE_DESCRIPTION },
+        { property: 'og:url', content: SITE_ORIGIN },
+        { property: 'og:image', content: OG_IMAGE_URL },
+        { property: 'og:image:secure_url', content: OG_IMAGE_URL },
+        { property: 'og:image:type', content: 'image/png' },
+        { property: 'og:image:width', content: '1200' },
+        { property: 'og:image:height', content: '630' },
+        { property: 'og:image:alt', content: SITE_NAME },
+      ],
       script: [{
         tagPosition: 'head',
         innerHTML: `try{var t=localStorage.getItem('ui-theme');var dark=t?t==='dark':matchMedia('(prefers-color-scheme: dark)').matches;document.documentElement.dataset.theme=dark?'dark':'light';document.documentElement.classList.toggle('dark',dark)}catch(e){}`,

docs/shared/site.ts

@@ -0,0 +1,20 @@
+/** Production origin of the docs site, as documented in the README. */
+export const SITE_ORIGIN = 'https://ui.froq.me'
+
+export const SITE_NAME = 'froq/ui'
+
+export const OG_IMAGE_URL = `${SITE_ORIGIN}/og.png`
+
+export const SITE_DESCRIPTION = 'Small controls, shared behavior, one visual language. Built for froq’s projects, with the details still open to refinement.'
+
+export function canonicalUrl(path: string): string {
+  if (!path || path === '/')
+    return SITE_ORIGIN
+  return `${SITE_ORIGIN}${path}`
+}
+
+export function shareTitle(title: string | undefined | null): string {
+  if (!title || title === SITE_NAME)
+    return SITE_NAME
+  return `${title} — ${SITE_NAME}`
+}