@levino/shipyard-base 0.8.0 → 0.8.1-rc-20260509120402

package/astro/layouts/Markdown.astro

@@ -1,4 +1,5 @@
 ---
+import type { ImageMetadata } from 'astro'
 import type { NavigationTree } from '../../src/schemas/config'
 import Base from './Page.astro'
 
@@ -17,9 +18,11 @@ type Props = {
      */
     keywords?: string[]
     /**
-     * Social card/preview image.
+     * Social card/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.
      */

package/astro/layouts/Page.astro

@@ -1,7 +1,9 @@
 ---
 import 'virtual:shipyard/css'
+import { getImage } from 'astro:assets'
 import { i18n } from 'astro:config/server'
 import config from 'virtual:shipyard/config'
+import type { ImageMetadata } from 'astro'
 import { mapObjIndexed } from 'ramda'
 import type {
   NavigationEntry,
@@ -24,12 +26,14 @@ type CustomMetaTag = {
   content: string
 }
 
+type PageImage = string | ImageMetadata
+
 type Props = {
   frontmatter?: {
     title?: string
     description?: string
     keywords?: string[]
-    image?: string
+    image?: PageImage
     canonicalUrl?: string
     customMetaTags?: CustomMetaTag[]
     sidebarNavigation?: NavigationTree
@@ -38,7 +42,7 @@ type Props = {
   title?: string
   description?: string
   keywords?: string[]
-  image?: string
+  image?: PageImage
   canonicalUrl?: string
   customMetaTags?: CustomMetaTag[]
   sidebarNavigation?: NavigationTree
@@ -47,6 +51,49 @@ type Props = {
 const currentPath = Astro.url.pathname
 const props = Astro.props.frontmatter || Astro.props
 
+const isImageMetadata = (value: PageImage): value is ImageMetadata =>
+  typeof value === 'object' && value !== null && 'src' in value
+
+const toAbsoluteUrl = (url: string) => {
+  if (/^https?:\/\//i.test(url)) return url
+  if (!Astro.site) return url
+  return new URL(url, Astro.site).href
+}
+
+type OgImageData = {
+  src: string
+  width?: number
+  height?: number
+  type?: string
+}
+
+const resolveOgImage = async (
+  value: PageImage | undefined,
+): Promise<OgImageData | undefined> => {
+  if (!value) return undefined
+  if (typeof value === 'string') return { src: value }
+  if (!isImageMetadata(value)) return undefined
+  // 1200x630 JPEG keeps OG cards under ~200 KB so WhatsApp/Telegram fetch the
+  // preview; re-encoding via Sharp also strips EXIF.
+  const optimized = await getImage({
+    src: value,
+    width: 1200,
+    height: 630,
+    format: 'jpeg',
+    fit: 'cover',
+  })
+  return {
+    src: optimized.src,
+    width: 1200,
+    height: 630,
+    type: 'image/jpeg',
+  }
+}
+
+const ogImageData = await resolveOgImage(props.image ?? config.defaultImage)
+const ogImageUrl = ogImageData ? toAbsoluteUrl(ogImageData.src) : undefined
+const ogImageAlt = props.description
+
 const withLocale = (path: string) =>
   i18n ? `/${Astro.currentLocale}${path}` : path
 const applyLocaleAndSetActive: (nav: NavigationTree) => NavigationTree =
@@ -85,11 +132,26 @@ const renderScriptAttributes = (script: Script) => {
     )}
     <meta property="og:title" content={title} />
     <meta property="og:description" content={props.description} />
-    {props.image && (
+    {ogImageData && ogImageUrl && (
       <>
-        <meta property="og:image" content={props.image} />
+        <meta property="og:image" content={ogImageUrl} />
+        {ogImageData.width && (
+          <meta property="og:image:width" content={String(ogImageData.width)} />
+        )}
+        {ogImageData.height && (
+          <meta property="og:image:height" content={String(ogImageData.height)} />
+        )}
+        {ogImageData.type && (
+          <meta property="og:image:type" content={ogImageData.type} />
+        )}
+        {ogImageAlt && (
+          <meta property="og:image:alt" content={ogImageAlt} />
+        )}
         <meta name="twitter:card" content="summary_large_image" />
-        <meta name="twitter:image" content={props.image} />
+        <meta name="twitter:image" content={ogImageUrl} />
+        {ogImageAlt && (
+          <meta name="twitter:image:alt" content={ogImageAlt} />
+        )}
       </>
     )}
     {props.canonicalUrl && (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-base",
-  "version": "0.8.0",
+  "version": "0.8.1-rc-20260509120402",
   "description": "Core layouts, components, and configuration for shipyard - a composable page builder for Astro",
   "keywords": [
     "astro",
@@ -39,7 +39,7 @@
   },
   "peerDependencies": {
     "@tailwindcss/typography": "^0.5.10",
-    "astro": "^6.0.0",
+    "astro": "^6.1.6",
     "daisyui": "^5",
     "tailwindcss": "^4"
   },
@@ -60,12 +60,13 @@
     "remark-html": "^16.0.1",
     "tailwindcss": "^4",
     "typescript": "^5.2.2",
-    "vite": "^7",
+    "vite": "^7.3.2",
     "vitest": "^4.1.0"
   },
   "dependencies": {
     "clsx": "^2.1.0",
     "mdast-util-directive": "^3.0.0",
+    "micromark-extension-directive": "^3.0.0",
     "ramda": "^0.31",
     "remark-directive": "^3.0.0",
     "tailwind-merge": "^2.2.0",

package/src/index.ts

@@ -1,7 +1,7 @@
 import { fileURLToPath } from 'node:url'
 import type { AstroIntegration } from 'astro'
-import remarkDirective from 'remark-directive'
 import { remarkAdmonitions } from './remark/remarkAdmonitions'
+import { remarkBlockDirective } from './remark/remarkBlockDirective'
 import { remarkNpm2Yarn } from './remark/remarkNpm2Yarn'
 import type { Config } from './schemas/config'
 import { checkLinks, reportBrokenLinks } from './tools/linkChecker'
@@ -47,7 +47,11 @@ export default (config: Config): AstroIntegration => {
 
         updateConfig({
           markdown: {
-            remarkPlugins: [remarkDirective, remarkAdmonitions, remarkNpm2Yarn],
+            remarkPlugins: [
+              remarkBlockDirective,
+              remarkAdmonitions,
+              remarkNpm2Yarn,
+            ],
           },
           vite: {
             plugins: [

package/src/remark/index.ts

@@ -9,4 +9,5 @@
 // Re-export remark-directive for convenience
 export { default as remarkDirective } from 'remark-directive'
 export { type AdmonitionType, remarkAdmonitions } from './remarkAdmonitions'
+export { remarkBlockDirective } from './remarkBlockDirective'
 export { remarkNpm2Yarn } from './remarkNpm2Yarn'

package/src/remark/remarkBlockDirective.test.ts

@@ -0,0 +1,69 @@
+import { remark } from 'remark'
+import remarkHtml from 'remark-html'
+import { describe, expect, it } from 'vitest'
+import { remarkAdmonitions } from './remarkAdmonitions'
+import { remarkBlockDirective } from './remarkBlockDirective'
+
+const process = async (markdown: string): Promise<string> => {
+  const result = await remark()
+    .use(remarkBlockDirective)
+    .use(remarkAdmonitions)
+    .use(remarkHtml, { sanitize: false })
+    .process(markdown)
+  return String(result)
+}
+
+describe('remarkBlockDirective', () => {
+  describe('German gender colon', () => {
+    it('does not split paragraphs containing :innen', async () => {
+      const input =
+        'herzlicher Dank an die Organisator:innen vom **ADFC** und an alle Ordner:innen'
+      const result = await process(input)
+      expect(result).toContain('Organisator:innen')
+      expect(result).toContain('Ordner:innen')
+      expect(result).not.toContain('<div></div>')
+    })
+
+    it('preserves :innen inside a paragraph as plain text', async () => {
+      const input = 'Liebe Anwohner:innen, willkommen.'
+      const result = await process(input)
+      expect(result).toContain('Liebe Anwohner:innen, willkommen.')
+    })
+
+    it('handles multiple gender colon variants in one paragraph', async () => {
+      const input = 'Mitarbeiter:innen, Lehrer:innen und Schüler:innen.'
+      const result = await process(input)
+      expect(result).toContain(
+        'Mitarbeiter:innen, Lehrer:innen und Schüler:innen.',
+      )
+      expect(result).not.toContain('<div></div>')
+    })
+  })
+
+  describe('container directives', () => {
+    it('still parses :::note admonitions', async () => {
+      const input = ':::note\nThis is a note\n:::'
+      const result = await process(input)
+      expect(result).toContain('admonition')
+      expect(result).toContain('admonition-note')
+      expect(result).toContain('This is a note')
+    })
+
+    it('still parses :::warning with custom title', async () => {
+      const input = ':::warning[Be Careful]\nWatch out\n:::'
+      const result = await process(input)
+      expect(result).toContain('admonition-warning')
+      expect(result).toContain('Be Careful')
+    })
+  })
+
+  describe('inline text directives', () => {
+    it('does not consume :name as a directive', async () => {
+      const input = 'Use :foo as a marker.'
+      const result = await process(input)
+      // Without text-directive support `:foo` stays as plain text.
+      expect(result).toContain(':foo')
+      expect(result).not.toContain('<div></div>')
+    })
+  })
+})

package/src/remark/remarkBlockDirective.ts

@@ -0,0 +1,35 @@
+import type { Root } from 'mdast'
+import { directiveFromMarkdown } from 'mdast-util-directive'
+import { directive } from 'micromark-extension-directive'
+import type { Plugin, Processor } from 'unified'
+
+/**
+ * Like `remark-directive`, but only enables block-level directives — container
+ * (`:::name`) and leaf (`::name`) — and disables inline text directives
+ * (`:name`).
+ *
+ * Why: the inline text directive syntax conflicts with the German gender
+ * colon (e.g. `Organisator:innen`, `Ordner:innen`), which would otherwise be
+ * tokenised as a directive and rendered as an empty `<div>`, tearing the
+ * surrounding paragraph apart.
+ *
+ * Block directives stay available so admonitions (`:::note`, `:::warning`)
+ * keep working.
+ */
+export const remarkBlockDirective: Plugin<[], Root> = function () {
+  const self = this as unknown as Processor<Root>
+  const data = self.data()
+
+  if (!data.micromarkExtensions) {
+    data.micromarkExtensions = []
+  }
+  if (!data.fromMarkdownExtensions) {
+    data.fromMarkdownExtensions = []
+  }
+
+  const { flow } = directive()
+  data.micromarkExtensions.push({ flow })
+  data.fromMarkdownExtensions.push(directiveFromMarkdown())
+}
+
+export default remarkBlockDirective

package/src/schemas/config.ts

@@ -201,6 +201,22 @@ export interface Config {
   navigation: NavigationTree
   title: string
   tagline: string
+  /**
+   * Default social preview image URL used as a fallback for pages that don't
+   * specify their own `image` in frontmatter.
+   *
+   * Accepts an absolute URL (e.g. `https://example.com/og.jpg`) or a path
+   * relative to the site root (e.g. `/og-default.jpg` for a file in `public/`).
+   * The path is resolved against `site` from `astro.config.*` to produce an
+   * absolute URL in the emitted `og:image` / `twitter:image` meta tags.
+   *
+   * For best results across Facebook, LinkedIn, Twitter and chat clients
+   * (WhatsApp, Telegram), use a 1200×630 JPEG under ~200 KB.
+   *
+   * @example '/og-default.jpg'
+   * @example 'https://example.com/og.jpg'
+   */
+  defaultImage?: string
   /**
    * Path to your app's CSS entry point.
    * This file should set up Tailwind CSS with @source directives for shipyard packages.