fix: standardize blog cover presentation

.gitignore

@@ -24,11 +24,13 @@ yarn-error.log*
 .env*.local
 .vercel
 next-env.d.ts
+/AGENTS.md
+/CLAUDE.md
 
 __pycache__/
 .vscode/
 
 api-reference/nodejs-api/index.d.ts
 
 public/api-reference/nodejs/
-public/api-reference/python/
+public/api-reference/python/

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Blog contribution guide
+
+Every post must provide a repository-hosted cover image. The blog index uses one predictable presentation rule for every cover, so article-specific fit overrides are not supported.
+
+## Cover requirements
+
+- Store cover assets under `public/img/blog/<post-slug>/` and reference them with `/img/blog/<post-slug>/<file>`.
+- Use a 16:9 landscape canvas. Recommended export size: `1600x900` or `1920x1080`; minimum accepted size: `800x450`.
+- Keep titles, logos, diagrams, and other essential content inside a 7% safe margin. Covers are displayed with `object-fit: cover` and may lose a very small edge area because of responsive rounding.
+- Prefer providing both `image` and `imageDark`, designed for light and dark page backgrounds respectively. Both covers must use the same dimensions, composition, and safe-area rules.
+- Do not use remote image URLs or add per-post CSS/object-fit exceptions.
+
+## Frontmatter
+
+```yaml
+---
+title: "Post title"
+date: "YYYY-MM-DD"
+image: /img/blog/YYYY-MM-DD-post-slug/header.webp
+imageDark: /img/blog/YYYY-MM-DD-post-slug/header-dark.webp # optional
+description: "Short summary"
+---
+```
+
+## Before opening a PR
+
+Run:
+
+```bash
+npm run blog:covers:check
+npm run types:check
+npm run build
+```
+
+`npm run build` also runs the cover check. A blog PR with a missing, remote, undersized, or incorrectly proportioned cover will fail CI before deployment.

app/[lang]/(home)/blog/page.tsx

@@ -100,13 +100,15 @@ function BlogCover({
         src={image}
         alt={title}
         loading={loading}
+        decoding="async"
       />
       {imageDark && (
         <img
           className="hidden dark:block"
           src={imageDark}
           alt=""
           loading={loading}
+          decoding="async"
           aria-hidden="true"
         />
       )}

app/global.css

@@ -6218,17 +6218,22 @@ body:has(.zvec-docs-overview) #nd-sidebar > div:nth-child(2) {
 
 
 .zvec-blog-featured-media {
-  min-height: 330px;
+  position: relative;
+  min-height: 0;
+  aspect-ratio: 16 / 9;
   overflow: hidden;
   border-right: 1px solid var(--zvec-border);
   background: var(--zvec-muted-surface);
 }
 
 
 .zvec-blog-featured-media img {
+  position: absolute;
+  inset: 0;
   width: 100%;
   height: 100%;
-  object-fit: contain;
+  object-fit: cover;
+  object-position: center;
   transition: transform 240ms ease;
 }
 
@@ -6243,25 +6248,29 @@ body:has(.zvec-docs-overview) #nd-sidebar > div:nth-child(2) {
   min-width: 0;
   flex-direction: column;
   justify-content: center;
-  padding: 34px;
+  padding: 28px;
 }
 
 
 .zvec-blog-featured-body h2 {
   margin-top: 18px;
   color: var(--zvec-ink);
-  font-size: clamp(1.75rem, 3vw, 2.65rem);
+  font-size: clamp(1.75rem, 2.7vw, 2.4rem);
   font-weight: 680;
   letter-spacing: -0.045em;
   line-height: 1.06;
 }
 
 
 .zvec-blog-featured-body > p {
+  display: -webkit-box;
+  overflow: hidden;
   margin-top: 14px;
   color: var(--zvec-muted);
   font-size: 0.9rem;
   line-height: 1.6;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
 }
 
 
@@ -6331,9 +6340,12 @@ body:has(.zvec-docs-overview) #nd-sidebar > div:nth-child(2) {
 
 
 .zvec-blog-card-media img {
+  position: absolute;
+  inset: 0;
   width: 100%;
   height: 100%;
-  object-fit: contain;
+  object-fit: cover;
+  object-position: center;
   transition: transform 240ms ease;
 }
 
@@ -6807,7 +6819,7 @@ a.zvec-map-tile:is(:hover, :focus-visible),
 }
 
 
-@media (max-width: 780px) {
+@media (max-width: 1199px) {
   .zvec-blog-featured-card {
     grid-template-columns: 1fr;
   }
@@ -6822,6 +6834,10 @@ a.zvec-map-tile:is(:hover, :focus-visible),
   .zvec-blog-featured-body {
     padding: 24px;
   }
+}
+
+
+@media (max-width: 780px) {
 
   .zvec-grep-diagram {
     gap: 18px;

content/blog/en/2026-09-08-zvec-rabitq.mdx

@@ -2,6 +2,7 @@
 title: "RaBitQ in Zvec: Quantization Principles, Index Design, and Benchmarks"
 date: "2026-09-08"
 image: /img/blog/2026-09-08-zvec-rabitq/header.png
+imageDark: /img/blog/2026-09-08-zvec-rabitq/header-dark.jpg
 description: "Explore native HNSW-RaBitQ and IVF-RaBitQ in Zvec through benchmarks, usage examples, randomized vector quantization, error bounds, and index design."
 ---
 

content/blog/en/2026-09-17-zvec-multi-platform.mdx

@@ -2,6 +2,7 @@
 title: "Making Vector Search Available Everywhere: A Complete View of Zvec Multi-Platform Support"
 date: "2026-09-17"
 image: /img/blog/2026-09-17-zvec-multi-platform/header.webp
+imageDark: /img/blog/2026-09-17-zvec-multi-platform/header-dark.jpg
 description: "Zvec runs wherever your application runs: Linux, macOS, Windows, Android, and iOS, with official SDKs for Python, Node.js, Go, Rust, Java, and Dart/Flutter plus ready-to-use prebuilt binaries. A complete inventory of CI-verified platforms, per-platform index availability, and the cross-platform engineering foundation behind them."
 ---
 

content/blog/zh/2026-09-08-zvec-rabitq.mdx

@@ -2,6 +2,7 @@
 title: "RaBitQ 落地 Zvec：量化原理、索引设计与性能实测"
 date: "2026-09-08"
 image: /img/blog/2026-09-08-zvec-rabitq/header.png
+imageDark: /img/blog/2026-09-08-zvec-rabitq/header-dark.jpg
 description: "Zvec 原生集成 HNSW-RaBitQ 与 IVF-RaBitQ：从性能实测和使用示例，理解随机化向量量化、误差界与索引实现。"
 ---
 

content/blog/zh/2026-09-17-zvec-multi-platform.mdx

@@ -2,6 +2,7 @@
 title: "让向量检索随处可用：Zvec 多平台支持全景"
 date: "2026-09-17"
 image: /img/blog/2026-09-17-zvec-multi-platform/header.webp
+imageDark: /img/blog/2026-09-17-zvec-multi-platform/header-dark.jpg
 description: "Zvec 已支持 Linux、macOS、Windows、Android 与 iOS，提供 Python、Node.js、Go、Rust、Java、Dart/Flutter 六种官方 SDK 与开箱即用的预编译产物。本文完整盘点 CI 验证的平台、各平台索引可用性、不同内存预算下的选型思路，以及背后的跨平台工程底座。"
 ---
 

package.json

@@ -3,7 +3,8 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "build": "next build",
+    "build": "npm run blog:covers:check && next build",
+    "blog:covers:check": "node --test scripts/validate-blog-covers.test.mjs && node scripts/validate-blog-covers.mjs",
     "dev": "next dev",
     "start": "next start",
     "types:check": "fumadocs-mdx && tsc --noEmit",

scripts/validate-blog-covers.mjs

@@ -0,0 +1,196 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { frontmatter } from 'fumadocs-core/content/md/frontmatter';
+
+const ROOT = process.cwd();
+const BLOG_ROOT = path.join(ROOT, 'content', 'blog');
+const PUBLIC_ROOT = path.join(ROOT, 'public');
+const TARGET_RATIO = 16 / 9;
+const MAX_RATIO_ERROR = 0.02;
+const MIN_WIDTH = 800;
+const MIN_HEIGHT = 450;
+
+async function walk(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(entries.map(async (entry) => {
+    const target = path.join(directory, entry.name);
+    return entry.isDirectory() ? walk(target) : [target];
+  }));
+  return files.flat();
+}
+
+export function readFrontmatter(source) {
+  const data = frontmatter(source).data;
+  return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+}
+
+export function validateCoverFields(fields, owner) {
+  const covers = [];
+  const errors = [];
+  const image = typeof fields.image === 'string' ? fields.image.trim() : '';
+
+  if (!image) {
+    errors.push(`${owner}: image is required and must be a local /img/blog/... path`);
+  } else {
+    covers.push({ key: 'image', image });
+  }
+
+  if (fields.imageDark !== undefined && fields.imageDark !== null) {
+    if (typeof fields.imageDark !== 'string') {
+      errors.push(`${owner}: imageDark must be a local /img/blog/... path when provided`);
+    } else if (fields.imageDark.trim()) {
+      covers.push({ key: 'imageDark', image: fields.imageDark.trim() });
+    }
+  }
+
+  return { covers, errors };
+}
+
+function pngSize(buffer) {
+  if (buffer.subarray(1, 4).toString() !== 'PNG') return null;
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+
+function jpegSize(buffer) {
+  if (buffer[0] !== 0xff || buffer[1] !== 0xd8) return null;
+  let offset = 2;
+
+  while (offset + 9 < buffer.length) {
+    if (buffer[offset] !== 0xff) {
+      offset += 1;
+      continue;
+    }
+
+    const marker = buffer[offset + 1];
+    offset += 2;
+    if (marker === 0xd8 || marker === 0xd9) continue;
+    const length = buffer.readUInt16BE(offset);
+    if ([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf].includes(marker)) {
+      return { width: buffer.readUInt16BE(offset + 5), height: buffer.readUInt16BE(offset + 3) };
+    }
+    offset += length;
+  }
+  return null;
+}
+
+function webpSize(buffer) {
+  if (buffer.subarray(0, 4).toString() !== 'RIFF' || buffer.subarray(8, 12).toString() !== 'WEBP') return null;
+  let offset = 12;
+
+  while (offset + 8 <= buffer.length) {
+    const type = buffer.subarray(offset, offset + 4).toString();
+    const length = buffer.readUInt32LE(offset + 4);
+    const data = offset + 8;
+
+    if (type === 'VP8X' && data + 10 <= buffer.length) {
+      return {
+        width: 1 + buffer.readUIntLE(data + 4, 3),
+        height: 1 + buffer.readUIntLE(data + 7, 3),
+      };
+    }
+    if (type === 'VP8 ' && data + 10 <= buffer.length) {
+      return {
+        width: buffer.readUInt16LE(data + 6) & 0x3fff,
+        height: buffer.readUInt16LE(data + 8) & 0x3fff,
+      };
+    }
+    if (type === 'VP8L' && data + 5 <= buffer.length && buffer[data] === 0x2f) {
+      const bits = buffer.readUInt32LE(data + 1);
+      return {
+        width: 1 + (bits & 0x3fff),
+        height: 1 + ((bits >> 14) & 0x3fff),
+      };
+    }
+
+    offset = data + length + (length % 2);
+  }
+  return null;
+}
+
+function svgSize(buffer) {
+  const source = buffer.toString('utf8', 0, Math.min(buffer.length, 4096));
+  if (!/<svg\b/i.test(source)) return null;
+  const viewBox = source.match(/viewBox=["']\s*[-\d.]+\s+[-\d.]+\s+([\d.]+)\s+([\d.]+)\s*["']/i);
+  if (viewBox) return { width: Number(viewBox[1]), height: Number(viewBox[2]) };
+  const width = source.match(/\bwidth=["']([\d.]+)/i);
+  const height = source.match(/\bheight=["']([\d.]+)/i);
+  return width && height ? { width: Number(width[1]), height: Number(height[1]) } : null;
+}
+
+function imageSize(buffer) {
+  return pngSize(buffer) || jpegSize(buffer) || webpSize(buffer) || svgSize(buffer);
+}
+
+export async function validateBlogCovers() {
+  const contentFiles = (await walk(BLOG_ROOT)).filter((file) => file.endsWith('.mdx'));
+  const references = new Map();
+  const errors = [];
+
+  for (const contentFile of contentFiles) {
+    const owner = path.relative(ROOT, contentFile);
+    let fields;
+    try {
+      fields = readFrontmatter(await readFile(contentFile, 'utf8'));
+    } catch (error) {
+      errors.push(`${owner}: invalid YAML frontmatter (${error instanceof Error ? error.message : String(error)})`);
+      continue;
+    }
+
+    const result = validateCoverFields(fields, owner);
+    errors.push(...result.errors);
+    for (const { key, image } of result.covers) {
+      if (!image.startsWith('/img/blog/')) {
+        errors.push(`${owner}: ${key} must be a local /img/blog/... path`);
+        continue;
+      }
+      const owners = references.get(image) || [];
+      owners.push(`${owner} (${key})`);
+      references.set(image, owners);
+    }
+  }
+
+  for (const [image, owners] of references) {
+    const asset = path.resolve(PUBLIC_ROOT, `.${image}`);
+    if (!asset.startsWith(`${PUBLIC_ROOT}${path.sep}`)) {
+      errors.push(`${image}: path escapes public/`);
+      continue;
+    }
+
+    let buffer;
+    try {
+      buffer = await readFile(asset);
+    } catch {
+      errors.push(`${image}: file does not exist (used by ${owners.join(', ')})`);
+      continue;
+    }
+
+    const size = imageSize(buffer);
+    if (!size || !Number.isFinite(size.width) || !Number.isFinite(size.height)) {
+      errors.push(`${image}: unsupported image or unreadable dimensions`);
+      continue;
+    }
+
+    const ratioError = Math.abs(size.width / size.height - TARGET_RATIO) / TARGET_RATIO;
+    if (ratioError > MAX_RATIO_ERROR) {
+      errors.push(`${image}: ${size.width}x${size.height} is not 16:9 (maximum deviation: 2%)`);
+    }
+    if (size.width < MIN_WIDTH || size.height < MIN_HEIGHT) {
+      errors.push(`${image}: ${size.width}x${size.height} is smaller than ${MIN_WIDTH}x${MIN_HEIGHT}`);
+    }
+  }
+
+  return { references, errors };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const { references, errors } = await validateBlogCovers();
+  if (errors.length > 0) {
+    console.error('Blog cover validation failed:\n');
+    for (const error of errors) console.error(`- ${error}`);
+    process.exitCode = 1;
+  } else {
+    console.log(`Validated ${references.size} blog cover assets (16:9, local, minimum ${MIN_WIDTH}x${MIN_HEIGHT}).`);
+  }
+}