blume 0.8.0 → 1.0.0

package/src/core/ui-packs/tr.ts

@@ -24,6 +24,10 @@ export const tr: UIStringsOverride = {
     title: "Yapay zekâya sor",
   },
   banner: { dismiss: "Duyuruyu kapat" },
+  changelog: {
+    description: "Ürün güncellemeleri ve sürüm notları.",
+    title: "Değişiklik günlüğü",
+  },
   feedback: {
     no: "Hayır",
     question: "Bu sayfa yardımcı oldu mu?",
@@ -31,13 +35,16 @@ export const tr: UIStringsOverride = {
     yes: "Evet",
   },
   languageSwitcher: { label: "Dil", untranslated: "Çevrilmemiş" },
+  nav: { breadcrumb: "Gezinme yolu" },
   page: {
     lastUpdated: "Son güncelleme",
     next: "Sonraki",
+    pagination: "Sayfalama",
     previous: "Önceki",
     skipToContent: "İçeriğe geç",
   },
   search: {
+    all: "Tümü",
     button: "Ara",
     devOnly: "Arama, üretim derlemesinde kullanılabilir.",
     label: "Belgelerde ara",

package/src/core/ui-packs/uk.ts

@@ -24,6 +24,10 @@ export const uk: UIStringsOverride = {
     title: "Запитати ШІ",
   },
   banner: { dismiss: "Закрити оголошення" },
+  changelog: {
+    description: "Оновлення продукту та примітки до випусків.",
+    title: "Журнал змін",
+  },
   feedback: {
     no: "Ні",
     question: "Чи була ця сторінка корисною?",
@@ -31,13 +35,16 @@ export const uk: UIStringsOverride = {
     yes: "Так",
   },
   languageSwitcher: { label: "Мова", untranslated: "Не перекладено" },
+  nav: { breadcrumb: "Навігаційний ланцюжок" },
   page: {
     lastUpdated: "Останнє оновлення",
     next: "Далі",
+    pagination: "Пагінація",
     previous: "Назад",
     skipToContent: "Перейти до вмісту",
   },
   search: {
+    all: "Усі",
     button: "Пошук",
     devOnly: "Пошук доступний у production-збірці.",
     label: "Пошук у документації",

package/src/core/ui-packs/vi.ts

@@ -24,6 +24,10 @@ export const vi: UIStringsOverride = {
     title: "Hỏi AI",
   },
   banner: { dismiss: "Đóng thông báo" },
+  changelog: {
+    description: "Cập nhật sản phẩm và ghi chú phát hành.",
+    title: "Nhật ký thay đổi",
+  },
   feedback: {
     no: "Không",
     question: "Trang này có hữu ích không?",
@@ -31,13 +35,16 @@ export const vi: UIStringsOverride = {
     yes: "Có",
   },
   languageSwitcher: { label: "Ngôn ngữ", untranslated: "Chưa dịch" },
+  nav: { breadcrumb: "Đường dẫn điều hướng" },
   page: {
     lastUpdated: "Cập nhật lần cuối",
     next: "Tiếp theo",
+    pagination: "Phân trang",
     previous: "Trước",
     skipToContent: "Chuyển đến nội dung",
   },
   search: {
+    all: "Tất cả",
     button: "Tìm kiếm",
     devOnly: "Tìm kiếm có sẵn trong bản dựng production.",
     label: "Tìm kiếm tài liệu",

package/src/core/ui-packs/zh-tw.ts

@@ -24,6 +24,10 @@ export const zhTW: UIStringsOverride = {
     title: "向 AI 提問",
   },
   banner: { dismiss: "關閉公告" },
+  changelog: {
+    description: "產品更新與版本說明。",
+    title: "更新日誌",
+  },
   feedback: {
     no: "沒有幫助",
     question: "這個頁面有幫助嗎？",
@@ -31,13 +35,16 @@ export const zhTW: UIStringsOverride = {
     yes: "有幫助",
   },
   languageSwitcher: { label: "語言", untranslated: "未翻譯" },
+  nav: { breadcrumb: "麵包屑導覽" },
   page: {
     lastUpdated: "最後更新於",
     next: "下一頁",
+    pagination: "分頁",
     previous: "上一頁",
     skipToContent: "跳至內容",
   },
   search: {
+    all: "全部",
     button: "搜尋",
     devOnly: "搜尋在正式版組建中可用。",
     label: "搜尋文件",

package/src/core/ui-packs/zh.ts

@@ -24,6 +24,10 @@ export const zh: UIStringsOverride = {
     title: "向 AI 提问",
   },
   banner: { dismiss: "关闭公告" },
+  changelog: {
+    description: "产品更新与版本说明。",
+    title: "更新日志",
+  },
   feedback: {
     no: "没有帮助",
     question: "这个页面有帮助吗？",
@@ -31,13 +35,16 @@ export const zh: UIStringsOverride = {
     yes: "有帮助",
   },
   languageSwitcher: { label: "语言", untranslated: "未翻译" },
+  nav: { breadcrumb: "面包屑导航" },
   page: {
     lastUpdated: "最后更新于",
     next: "下一页",
+    pagination: "分页",
     previous: "上一页",
     skipToContent: "跳到内容",
   },
   search: {
+    all: "全部",
     button: "搜索",
     devOnly: "搜索在生产构建中可用。",
     label: "搜索文档",

package/src/og/card.ts

@@ -2,6 +2,8 @@ import { Renderer } from "@takumi-rs/core";
 import { container, image, text } from "@takumi-rs/helpers";
 import type { Node } from "@takumi-rs/helpers";
 
+import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH } from "./dimensions.ts";
+
 // Reuse one renderer (and its loaded default fonts) across all images.
 let renderer: Renderer | null = null;
 const getRenderer = (): Renderer => {
@@ -53,8 +55,8 @@ export interface OgCardOptions {
   site?: string;
 }
 
-const WIDTH = 1200;
-const HEIGHT = 630;
+const WIDTH = OG_IMAGE_WIDTH;
+const HEIGHT = OG_IMAGE_HEIGHT;
 
 // Light neutral scale mirrored from the docs homepage theme tokens:
 // FOREGROUND = --foreground, MUTED = --muted-foreground, FAINT = that lighter,

package/src/og/dimensions.ts

@@ -0,0 +1,12 @@
+/**
+ * Dimensions of a generated OG card, shared by the renderer (`card.ts`) and the
+ * layouts that declare them as `og:image:width`/`og:image:height` so a crawler
+ * can lay out the card without fetching the PNG first.
+ *
+ * This lives apart from `card.ts` because that module imports the Takumi native
+ * binding at load; a layout importing it would drag the renderer into every
+ * page render (and into the prerender/SSR bundles that externalize it).
+ */
+export const OG_IMAGE_WIDTH = 1200;
+export const OG_IMAGE_HEIGHT = 630;
+export const OG_IMAGE_TYPE = "image/png";

package/src/openapi/render-mdx.ts

@@ -58,6 +58,61 @@ export interface RenderedPage {
   body: string;
 }
 
+// Meta descriptions. A page that sets none falls back to the site-wide default,
+// so a spec's pages would otherwise all ship one identical description — what
+// search engines treat as duplicate content. These go in `seo.description`, not
+// `description`: the prose already renders in the body, and a `description`
+// frontmatter field would print it a second time as the page subtitle.
+const META_DESCRIPTION_MAX = 160;
+const PARAGRAPH_BREAK = /\n\s*\n/u;
+const MARKDOWN_LINK = /\[(?<text>[^\]]*)\]\([^)]*\)/gu;
+const MARKDOWN_MARKS = /[*_`#>]/gu;
+const WHITESPACE = /\s+/gu;
+const TRAILING_WORD = /\s+\S*$/u;
+
+/** Flatten markdown prose to its first paragraph as single-line plain text. */
+const plainProse = (markdown: string): string =>
+  (markdown.trim().split(PARAGRAPH_BREAK).at(0) ?? "")
+    .replace(MARKDOWN_LINK, "$<text>")
+    .replace(MARKDOWN_MARKS, "")
+    .replace(WHITESPACE, " ")
+    .trim();
+
+/** Cap `text` at `max` characters, cutting on a word boundary. */
+const clip = (text: string, max: number): string => {
+  if (max <= 0) {
+    return "";
+  }
+  if (text.length <= max) {
+    return text;
+  }
+  const head = text.slice(0, max - 1);
+  const onWordBoundary = head.replace(TRAILING_WORD, "");
+  // One very long token — an endpoint path has no spaces — would be dropped
+  // whole, leaving a stub. Hard-cut it instead of losing it.
+  return `${onWordBoundary.length >= max / 2 ? onWordBoundary : head}…`;
+};
+
+const apiName = (spec: ApiSpecData): string => spec.title || spec.label;
+
+/**
+ * The spec's own prose for the operation, followed by the endpoint it documents
+ * — so every operation page carries a distinct, self-describing meta
+ * description even when the spec's summaries are terse.
+ */
+const operationDescription = (
+  spec: ApiSpecData,
+  operation: ApiOperationRef
+): string => {
+  const endpoint = `${operation.method.toUpperCase()} ${operation.path}`;
+  const suffix = `Reference for the ${endpoint} endpoint in the ${apiName(spec)} API.`;
+  const prose = clip(
+    plainProse(operation.description || operation.summary),
+    META_DESCRIPTION_MAX - suffix.length - 1
+  );
+  return clip([prose, suffix].filter(Boolean).join(" "), META_DESCRIPTION_MAX);
+};
+
 /** Prepend a markdown description (if any) above a component invocation. */
 const withDescription = (description: string, component: string): string =>
   description.trim()
@@ -84,6 +139,7 @@ export const operationMdx = (
     data: {
       ...(operation.deprecated ? { deprecated: true } : {}),
       search: { tags: [operation.tag, method] },
+      seo: { description: operationDescription(spec, operation) },
       sidebar: { badge: method, label: operation.summary || operation.path },
       title,
       // Signals the two-column API layout (request panel instead of the TOC).
@@ -144,8 +200,13 @@ export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
       ...tagSections,
     ].join("\n\n"),
     data: {
+      seo: {
+        description:
+          clip(plainProse(spec.description), META_DESCRIPTION_MAX) ||
+          `${apiName(spec)} API reference.`,
+      },
       sidebar: { label: "Overview" },
-      title: spec.title || spec.label,
+      title: apiName(spec),
     },
   };
 };

package/src/seo/jsonld.ts

@@ -37,7 +37,13 @@ const trimSlash = (value: string): string => value.replace(/\/$/u, "");
 const absolute = (base: string | null, path: string): string =>
   base ? `${base}${path}` : path;
 
-const toIso = (value: DateInput | undefined): string | undefined => {
+/**
+ * Frontmatter date → ISO 8601, or undefined when absent/unparseable. Shared with
+ * the layout's `article:published_time`/`article:modified_time` so both date
+ * surfaces treat a malformed date the same way: omit it rather than emit
+ * "Invalid Date".
+ */
+export const toIso = (value: DateInput | undefined): string | undefined => {
   if (!value) {
     return;
   }

package/src/seo/x-handle.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalize an X account to the leading `@` that `twitter:site`/`twitter:creator`
+ * require, so `acme`, `@acme`, and `  @acme ` all land on `@acme`. Empty or
+ * blank input yields undefined, which renders no tag at all.
+ *
+ * The layouts call this on values that never passed through the config schema:
+ * Astro's collections carry no schema here, so a page's `seo.x.creator` reaches
+ * them as raw frontmatter, and the schema's own transform never runs on it.
+ * (Blume's page pipeline does reject a non-string `creator` before the page is
+ * built, so `unknown` is defense in depth rather than the expected path.)
+ */
+export const normalizeXHandle = (value: unknown): string | undefined => {
+  if (typeof value !== "string") {
+    return;
+  }
+  const handle = value.trim().replace(/^@+/u, "");
+  return handle ? `@${handle}` : undefined;
+};