@levino/shipyard-docs 0.8.1-rc-20260509110053 → 0.8.1

package/astro/Layout.astro

@@ -11,6 +11,7 @@ import {
   VersionSelector,
 } from '@levino/shipyard-base/components'
 import BaseLayout from '@levino/shipyard-base/layouts/Page.astro'
+import type { ImageMetadata } from 'astro'
 import { experimental_AstroContainer as AstroContainer } from 'astro/container'
 import { Array as EffectArray, Option } from 'effect'
 import { getPaginationInfo } from '../src/pagination'
@@ -66,9 +67,11 @@ interface Props {
    */
   keywords?: string[]
   /**
-   * Social preview image URL (og:image).
+   * Social preview image. Accepts an absolute URL or, in content collections,
+   * an `ImageMetadata` from a relative path. Local images are automatically
+   * optimized to 1200×630 JPEG for OG/Twitter cards.
    */
-  image?: string
+  image?: string | ImageMetadata
   /**
    * Custom canonical URL for the page.
    */
@@ -86,6 +89,11 @@ interface Props {
    * Override title for SEO/browser tab (overrides the regular title in <title> tag).
    */
   titleMeta?: string
+  /**
+   * Page description used for `<meta name="description">` and as the default
+   * for `og:image:alt` / `twitter:image:alt`.
+   */
+  description?: string
 }
 
 const {
@@ -103,6 +111,7 @@ const {
   canonicalUrl,
   customMetaTags,
   titleMeta,
+  description,
 } = Astro.props
 
 // Normalize the route base path
@@ -318,7 +327,7 @@ const deprecationBannerProps =
     : null
 ---
 
-<BaseLayout sidebarNavigation={entries} keywords={keywords} image={image} canonicalUrl={canonicalUrl} customMetaTags={customMetaTags} title={titleMeta}>
+<BaseLayout sidebarNavigation={entries} keywords={keywords} image={image} canonicalUrl={canonicalUrl} customMetaTags={customMetaTags} title={titleMeta} description={description}>
   {
     versionSelectorProps && (
       <VersionSelector

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-docs",
-  "version": "0.8.1-rc-20260509110053",
+  "version": "0.8.1",
   "description": "Documentation plugin for shipyard with automatic sidebar, pagination, and git metadata",
   "type": "module",
   "main": "src/index.ts",
@@ -27,7 +27,7 @@
     "effect": "^3.20.0",
     "ramda": "^0.31",
     "unist-util-visit": "^5.0.0",
-    "@levino/shipyard-base": "0.8.1-rc-20260509110053"
+    "@levino/shipyard-base": "^0.8.1"
   },
   "devDependencies": {
     "@tailwindcss/typography": "^0.5.16",

package/src/index.ts

@@ -86,8 +86,14 @@ const docsSchemaBase = (image: () => z.ZodType) =>
     description: z.string().optional(),
     /** SEO keywords */
     keywords: z.array(z.string()).optional(),
-    /** Image for the page. Use a relative path to a local image file. */
-    image: image().optional(),
+    /**
+     * Social preview image. Accepts either:
+     * - A relative path to a local image file (e.g. `./hero.png`), which is
+     *   automatically optimized to 1200×630 JPEG for OG/Twitter cards.
+     * - An absolute URL (e.g. `https://example.com/og.jpg`), passed through
+     *   verbatim.
+     */
+    image: z.union([image(), z.string().url()]).optional(),
     /** Custom canonical URL */
     canonicalUrl: z.string().optional(),
     /** Custom canonical URL - snake_case alias for Docusaurus compatibility */
@@ -1015,7 +1021,7 @@ const displayVersion = version // The version shown in the URL
 
 const { Content, headings } = await render(entry)
 
-const { customEditUrl, lastUpdateAuthor, lastUpdateTime, hideTableOfContents, hideTitle, keywords, image, canonicalUrl, customMetaTags, title_meta: titleMeta } = entry.data
+const { customEditUrl, lastUpdateAuthor, lastUpdateTime, hideTableOfContents, hideTitle, keywords, image, canonicalUrl, customMetaTags, title_meta: titleMeta, description } = entry.data
 
 let editUrl
 if (customEditUrl === null) {
@@ -1065,7 +1071,7 @@ if (
 }
 ---
 
-<Layout headings={headings} routeBasePath={routeBasePath} editUrl={editUrl} lastUpdated={lastUpdated} lastAuthor={lastAuthor} hideTableOfContents={hideTableOfContents} hideTitle={hideTitle} keywords={keywords} image={image?.src} canonicalUrl={canonicalUrl} customMetaTags={customMetaTags} titleMeta={titleMeta}>
+<Layout headings={headings} routeBasePath={routeBasePath} editUrl={editUrl} lastUpdated={lastUpdated} lastAuthor={lastAuthor} hideTableOfContents={hideTableOfContents} hideTitle={hideTitle} keywords={keywords} image={image} canonicalUrl={canonicalUrl} customMetaTags={customMetaTags} titleMeta={titleMeta} description={description}>
   <Content />
 </Layout>
 `