blume 0.0.0 → 0.1.1

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Swedish (sv) UI strings. */
+export const sv: UIStringsOverride = {
+  actions: {
+    addToCursor: "Lägg till i Cursor",
+    addToVscode: "Lägg till i VS Code",
+    askAI: "Fråga AI om den här sidan",
+    connectMcp: "Anslut till MCP",
+    copied: "Kopierat!",
+    copyClaudeCode: "Kopiera Claude Code-kommando",
+    copyMarkdown: "Kopiera som Markdown",
+    copyServerUrl: "Kopiera server-URL",
+    edit: "Redigera på GitHub",
+    openInChat: "Öppna i chatt",
+    scrollToTop: "Till toppen",
+  },
+  ask: {
+    empty: "Ställ en fråga om dokumentationen.",
+    error: "Tyvärr, något gick fel.",
+    label: "Ställ en fråga",
+    placeholder: "Ställ en fråga…",
+    send: "Skicka",
+    title: "Fråga AI",
+  },
+  feedback: {
+    no: "Nej",
+    question: "Var den här sidan till hjälp?",
+    thanks: "Tack för din feedback!",
+    yes: "Ja",
+  },
+  languageSwitcher: { label: "Språk", untranslated: "Inte översatt" },
+  page: {
+    lastUpdated: "Senast uppdaterad",
+    next: "Nästa",
+    previous: "Föregående",
+    skipToContent: "Hoppa till innehåll",
+  },
+  search: {
+    button: "Sök",
+    devOnly: "Sökning är tillgänglig i produktionsbygget.",
+    label: "Sök i dokumentationen",
+    noResults: "Inga resultat hittades.",
+    placeholder: "Sök i dokumentationen…",
+  },
+  toc: { title: "På den här sidan" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Thai (th) UI strings. */
+export const th: UIStringsOverride = {
+  actions: {
+    addToCursor: "เพิ่มไปยัง Cursor",
+    addToVscode: "เพิ่มไปยัง VS Code",
+    askAI: "ถาม AI เกี่ยวกับหน้านี้",
+    connectMcp: "เชื่อมต่อกับ MCP",
+    copied: "คัดลอกแล้ว!",
+    copyClaudeCode: "คัดลอกคำสั่ง Claude Code",
+    copyMarkdown: "คัดลอกเป็น Markdown",
+    copyServerUrl: "คัดลอก URL ของเซิร์ฟเวอร์",
+    edit: "แก้ไขบน GitHub",
+    openInChat: "เปิดในแชท",
+    scrollToTop: "กลับไปด้านบน",
+  },
+  ask: {
+    empty: "ถามคำถามเกี่ยวกับเอกสาร",
+    error: "ขออภัย เกิดข้อผิดพลาดบางอย่าง",
+    label: "ถามคำถาม",
+    placeholder: "ถามคำถาม…",
+    send: "ส่ง",
+    title: "ถาม AI",
+  },
+  feedback: {
+    no: "ไม่",
+    question: "หน้านี้มีประโยชน์หรือไม่?",
+    thanks: "ขอบคุณสำหรับความคิดเห็นของคุณ!",
+    yes: "ใช่",
+  },
+  languageSwitcher: { label: "ภาษา", untranslated: "ยังไม่ได้แปล" },
+  page: {
+    lastUpdated: "อัปเดตล่าสุดเมื่อ",
+    next: "ถัดไป",
+    previous: "ก่อนหน้า",
+    skipToContent: "ข้ามไปยังเนื้อหา",
+  },
+  search: {
+    button: "ค้นหา",
+    devOnly: "การค้นหาพร้อมใช้งานในบิลด์โปรดักชัน",
+    label: "ค้นหาเอกสาร",
+    noResults: "ไม่พบผลลัพธ์",
+    placeholder: "ค้นหาเอกสาร…",
+  },
+  toc: { title: "ในหน้านี้" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Turkish (tr) UI strings. */
+export const tr: UIStringsOverride = {
+  actions: {
+    addToCursor: "Cursor'a ekle",
+    addToVscode: "VS Code'a ekle",
+    askAI: "Bu sayfa hakkında yapay zekâya sor",
+    connectMcp: "MCP'ye bağlan",
+    copied: "Kopyalandı!",
+    copyClaudeCode: "Claude Code komutunu kopyala",
+    copyMarkdown: "Markdown olarak kopyala",
+    copyServerUrl: "Sunucu URL'sini kopyala",
+    edit: "GitHub'da düzenle",
+    openInChat: "Sohbette aç",
+    scrollToTop: "Başa dön",
+  },
+  ask: {
+    empty: "Belgeler hakkında bir soru sorun.",
+    error: "Üzgünüz, bir şeyler ters gitti.",
+    label: "Bir soru sorun",
+    placeholder: "Bir soru sorun…",
+    send: "Gönder",
+    title: "Yapay zekâya sor",
+  },
+  feedback: {
+    no: "Hayır",
+    question: "Bu sayfa yardımcı oldu mu?",
+    thanks: "Geri bildiriminiz için teşekkürler!",
+    yes: "Evet",
+  },
+  languageSwitcher: { label: "Dil", untranslated: "Çevrilmemiş" },
+  page: {
+    lastUpdated: "Son güncelleme",
+    next: "Sonraki",
+    previous: "Önceki",
+    skipToContent: "İçeriğe geç",
+  },
+  search: {
+    button: "Ara",
+    devOnly: "Arama, üretim derlemesinde kullanılabilir.",
+    label: "Belgelerde ara",
+    noResults: "Sonuç bulunamadı.",
+    placeholder: "Belgelerde ara…",
+  },
+  toc: { title: "Bu sayfada" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Ukrainian (uk) UI strings. */
+export const uk: UIStringsOverride = {
+  actions: {
+    addToCursor: "Додати до Cursor",
+    addToVscode: "Додати до VS Code",
+    askAI: "Запитати ШІ про цю сторінку",
+    connectMcp: "Підключитися до MCP",
+    copied: "Скопійовано!",
+    copyClaudeCode: "Скопіювати команду Claude Code",
+    copyMarkdown: "Скопіювати як Markdown",
+    copyServerUrl: "Скопіювати URL сервера",
+    edit: "Редагувати на GitHub",
+    openInChat: "Відкрити в чаті",
+    scrollToTop: "Нагору",
+  },
+  ask: {
+    empty: "Поставте запитання щодо документації.",
+    error: "Вибачте, щось пішло не так.",
+    label: "Поставити запитання",
+    placeholder: "Поставте запитання…",
+    send: "Надіслати",
+    title: "Запитати ШІ",
+  },
+  feedback: {
+    no: "Ні",
+    question: "Чи була ця сторінка корисною?",
+    thanks: "Дякуємо за ваш відгук!",
+    yes: "Так",
+  },
+  languageSwitcher: { label: "Мова", untranslated: "Не перекладено" },
+  page: {
+    lastUpdated: "Останнє оновлення",
+    next: "Далі",
+    previous: "Назад",
+    skipToContent: "Перейти до вмісту",
+  },
+  search: {
+    button: "Пошук",
+    devOnly: "Пошук доступний у production-збірці.",
+    label: "Пошук у документації",
+    noResults: "Нічого не знайдено.",
+    placeholder: "Пошук у документації…",
+  },
+  toc: { title: "На цій сторінці" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Vietnamese (vi) UI strings. */
+export const vi: UIStringsOverride = {
+  actions: {
+    addToCursor: "Thêm vào Cursor",
+    addToVscode: "Thêm vào VS Code",
+    askAI: "Hỏi AI về trang này",
+    connectMcp: "Kết nối với MCP",
+    copied: "Đã sao chép!",
+    copyClaudeCode: "Sao chép lệnh Claude Code",
+    copyMarkdown: "Sao chép dưới dạng Markdown",
+    copyServerUrl: "Sao chép URL máy chủ",
+    edit: "Chỉnh sửa trên GitHub",
+    openInChat: "Mở trong trò chuyện",
+    scrollToTop: "Lên đầu trang",
+  },
+  ask: {
+    empty: "Đặt câu hỏi về tài liệu.",
+    error: "Xin lỗi, đã xảy ra sự cố.",
+    label: "Đặt câu hỏi",
+    placeholder: "Đặt câu hỏi…",
+    send: "Gửi",
+    title: "Hỏi AI",
+  },
+  feedback: {
+    no: "Không",
+    question: "Trang này có hữu ích không?",
+    thanks: "Cảm ơn phản hồi của bạn!",
+    yes: "Có",
+  },
+  languageSwitcher: { label: "Ngôn ngữ", untranslated: "Chưa dịch" },
+  page: {
+    lastUpdated: "Cập nhật lần cuối",
+    next: "Tiếp theo",
+    previous: "Trước",
+    skipToContent: "Chuyển đến nội dung",
+  },
+  search: {
+    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",
+    noResults: "Không tìm thấy kết quả.",
+    placeholder: "Tìm kiếm tài liệu…",
+  },
+  toc: { title: "Trên trang này" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Chinese — Traditional (zh-TW) UI strings. */
+export const zhTW: UIStringsOverride = {
+  actions: {
+    addToCursor: "新增至 Cursor",
+    addToVscode: "新增至 VS Code",
+    askAI: "向 AI 詢問此頁面",
+    connectMcp: "連線至 MCP",
+    copied: "已複製！",
+    copyClaudeCode: "複製 Claude Code 指令",
+    copyMarkdown: "複製為 Markdown",
+    copyServerUrl: "複製伺服器 URL",
+    edit: "在 GitHub 上編輯",
+    openInChat: "在聊天中開啟",
+    scrollToTop: "回到頂部",
+  },
+  ask: {
+    empty: "針對文件提出問題。",
+    error: "抱歉，發生了一些問題。",
+    label: "提出問題",
+    placeholder: "提出問題…",
+    send: "傳送",
+    title: "向 AI 提問",
+  },
+  feedback: {
+    no: "沒有幫助",
+    question: "這個頁面有幫助嗎？",
+    thanks: "感謝你的意見回饋！",
+    yes: "有幫助",
+  },
+  languageSwitcher: { label: "語言", untranslated: "未翻譯" },
+  page: {
+    lastUpdated: "最後更新於",
+    next: "下一頁",
+    previous: "上一頁",
+    skipToContent: "跳至內容",
+  },
+  search: {
+    button: "搜尋",
+    devOnly: "搜尋在正式版組建中可用。",
+    label: "搜尋文件",
+    noResults: "找不到結果。",
+    placeholder: "搜尋文件…",
+  },
+  toc: { title: "本頁內容" },
+};

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

@@ -0,0 +1,47 @@
+import type { UIStringsOverride } from "../i18n-ui.ts";
+
+/** Chinese — Simplified (zh) UI strings. */
+export const zh: UIStringsOverride = {
+  actions: {
+    addToCursor: "添加到 Cursor",
+    addToVscode: "添加到 VS Code",
+    askAI: "向 AI 询问此页面",
+    connectMcp: "连接到 MCP",
+    copied: "已复制！",
+    copyClaudeCode: "复制 Claude Code 命令",
+    copyMarkdown: "复制为 Markdown",
+    copyServerUrl: "复制服务器 URL",
+    edit: "在 GitHub 上编辑",
+    openInChat: "在聊天中打开",
+    scrollToTop: "回到顶部",
+  },
+  ask: {
+    empty: "就文档提出问题。",
+    error: "抱歉，出了点问题。",
+    label: "提出问题",
+    placeholder: "提出问题…",
+    send: "发送",
+    title: "向 AI 提问",
+  },
+  feedback: {
+    no: "没有帮助",
+    question: "这个页面有帮助吗？",
+    thanks: "感谢你的反馈！",
+    yes: "有帮助",
+  },
+  languageSwitcher: { label: "语言", untranslated: "未翻译" },
+  page: {
+    lastUpdated: "最后更新于",
+    next: "下一页",
+    previous: "上一页",
+    skipToContent: "跳到内容",
+  },
+  search: {
+    button: "搜索",
+    devOnly: "搜索在生产构建中可用。",
+    label: "搜索文档",
+    noResults: "未找到结果。",
+    placeholder: "搜索文档…",
+  },
+  toc: { title: "本页内容" },
+};

package/src/core/version.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+
+import { join } from "pathe";
+
+import { packageRoot } from "./package-root.ts";
+
+let cached: string | undefined;
+
+/**
+ * The installed Blume package version, read lazily from its `package.json`.
+ *
+ * Computed on demand (not at module load) so importing the `blume` barrel has no
+ * filesystem side effect, and anchored at the package root so it resolves the
+ * same whether running from source or the bundled CLI.
+ */
+export const getBlumeVersion = (): string => {
+  if (cached === undefined) {
+    const pkgPath = join(packageRoot(), "package.json");
+    cached = (JSON.parse(readFileSync(pkgPath, "utf-8")) as { version: string })
+      .version;
+  }
+  return cached;
+};

package/src/deploy/robots.ts

@@ -0,0 +1,20 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+
+/**
+ * Build a robots.txt that allows all crawlers and points to the sitemap when
+ * one is available (a `site` is set and the sitemap is enabled). Returns null
+ * when robots generation is disabled.
+ */
+export const buildRobots = (project: BlumeProject): string | null => {
+  const { config } = project;
+  if (!config.seo.robots) {
+    return null;
+  }
+
+  const lines = ["User-agent: *", "Allow: /"];
+  const { site } = config.deployment;
+  if (site && config.seo.sitemap) {
+    lines.push("", `Sitemap: ${site.replace(/\/$/u, "")}/sitemap.xml`);
+  }
+  return `${lines.join("\n")}\n`;
+};

package/src/deploy/rss.ts

@@ -0,0 +1,128 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { PageRecord } from "../core/types.ts";
+
+/** A single feed entry derived from a content page. */
+export interface RssItem {
+  title: string;
+  /** Absolute item URL. */
+  link: string;
+  description?: string;
+  /** Publish date, when the page declares one. */
+  date?: Date;
+}
+
+/** A resolved RSS feed for one content type. */
+export interface RssFeed {
+  /** Content type the feed covers, e.g. `blog`. */
+  type: string;
+  /** Feed URL path, e.g. `/blog/rss.xml`. */
+  path: string;
+  /** Channel title, e.g. `Blume — Blog`. */
+  title: string;
+  /** Absolute site link. */
+  link: string;
+  description?: string;
+  items: RssItem[];
+}
+
+const capitalize = (value: string): string =>
+  value.charAt(0).toUpperCase() + value.slice(1);
+
+/** Publish date for a page: top-level `date`, else `changelog.date`. */
+const pageDate = (page: PageRecord): Date | undefined => {
+  const raw = page.meta.date ?? page.meta.changelog?.date;
+  if (!raw) {
+    return;
+  }
+  const date = new Date(raw);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+};
+
+/**
+ * Build an RSS feed per configured content type that has publishable pages.
+ * Returns an empty list when RSS is disabled or no `deployment.site` is set —
+ * absolute URLs are required for a valid feed, mirroring `buildSitemap`.
+ */
+export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
+  const { config } = project;
+  const { rss } = config.seo;
+  const { site } = config.deployment;
+  if (!(rss.enabled && site)) {
+    return [];
+  }
+  const base = site.replace(/\/$/u, "");
+
+  const feeds: RssFeed[] = [];
+  for (const type of rss.types) {
+    const pages = project.graph.pages.filter(
+      (page) =>
+        page.contentType === type &&
+        !(page.meta.draft || page.meta.sidebar.hidden)
+    );
+    if (pages.length === 0) {
+      continue;
+    }
+
+    const items: RssItem[] = pages
+      .map((page) => ({
+        date: pageDate(page),
+        description: page.description,
+        link: `${base}${page.route}`,
+        title: page.title,
+      }))
+      .toSorted((a, b) => (b.date?.getTime() ?? 0) - (a.date?.getTime() ?? 0))
+      .slice(0, rss.limit);
+
+    feeds.push({
+      description: config.description,
+      items,
+      link: base,
+      path: `/${type}/rss.xml`,
+      title: `${config.title} — ${capitalize(type)}`,
+      type,
+    });
+  }
+  return feeds;
+};
+
+const escapeXml = (value: string): string =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+
+const renderItem = (item: RssItem): string => {
+  const parts = [
+    `    <title>${escapeXml(item.title)}</title>`,
+    `    <link>${escapeXml(item.link)}</link>`,
+    `    <guid isPermaLink="true">${escapeXml(item.link)}</guid>`,
+  ];
+  if (item.description) {
+    parts.push(`    <description>${escapeXml(item.description)}</description>`);
+  }
+  if (item.date) {
+    parts.push(`    <pubDate>${item.date.toUTCString()}</pubDate>`);
+  }
+  return `  <item>\n${parts.join("\n")}\n  </item>`;
+};
+
+/** Serialize a resolved feed into an RSS 2.0 XML document. */
+export const renderRssFeed = (feed: RssFeed): string => {
+  const channel = [
+    `  <title>${escapeXml(feed.title)}</title>`,
+    `  <link>${escapeXml(feed.link)}</link>`,
+    `  <description>${escapeXml(feed.description ?? feed.title)}</description>`,
+    `  <atom:link href="${escapeXml(`${feed.link}${feed.path}`)}" rel="self" type="application/rss+xml" />`,
+  ];
+  const items = feed.items.map(renderItem).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+<channel>
+${channel.join("\n")}
+${items}
+</channel>
+</rss>
+`;
+};

package/src/deploy/sitemap.ts

@@ -0,0 +1,28 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+
+/**
+ * Build a sitemap.xml from the route manifest. Returns null when the sitemap is
+ * disabled or no `site` is configured (absolute URLs are required for a valid
+ * sitemap). Drafts, hidden, and `noindex` pages are excluded.
+ */
+export const buildSitemap = (project: BlumeProject): string | null => {
+  const { site } = project.config.deployment;
+  if (!(site && project.config.seo.sitemap)) {
+    return null;
+  }
+
+  const base = site.replace(/\/$/u, "");
+  const urls = project.graph.pages
+    .filter(
+      (page) =>
+        !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)
+    )
+    .map((page) => `  <url><loc>${base}${page.route}</loc></url>`)
+    .toSorted();
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.join("\n")}
+</urlset>
+`;
+};

package/src/index.ts

@@ -0,0 +1,39 @@
+export { defineConfig } from "./core/config.ts";
+export type {
+  BlumeBanner,
+  BlumeData,
+  BlumeDataConfig,
+  BlumeDataI18n,
+  BlumeDataLocale,
+  BlumeFavicon,
+  BlumeFeed,
+  BlumeLogo,
+  BlumeRoute,
+} from "./core/data.ts";
+export { defineComponents } from "./core/define-components.ts";
+export type {
+  ComponentOverride,
+  ComponentOverrides,
+  IslandDescriptor,
+} from "./core/define-components.ts";
+export { defineMeta } from "./core/define-meta.ts";
+export type {
+  FolderMetaDefinition,
+  FolderMetaFactory,
+} from "./core/define-meta.ts";
+export type { UIStrings } from "./core/i18n-ui.ts";
+export type {
+  BlumeConfig,
+  FolderMeta,
+  HydrationMode,
+  ResolvedConfig,
+} from "./core/schema.ts";
+export type {
+  Diagnostic,
+  Heading,
+  NavNode,
+  Navigation,
+  NavTab,
+  PageRecord,
+} from "./core/types.ts";
+export { getBlumeVersion } from "./core/version.ts";

package/src/markdown/code-title.ts

@@ -0,0 +1,71 @@
+/**
+ * Code-fence meta. A Shiki transformer reads the tokens after the language and
+ * promotes them to attributes on the rendered `<pre>`:
+ *
+ * - a title — the first bare token (```ts blume.config.ts) or `title="..."` —
+ *   becomes `data-title`; the theme's code header shows it, falling back to the
+ *   language label.
+ * - the `lineNumbers` keyword (```ts file.ts lineNumbers) becomes
+ *   `data-line-numbers`; the theme renders a counter-driven line-number gutter.
+ */
+
+/** The slice of Shiki's transformer `this` context Blume reads. */
+interface CodeMetaContext {
+  options: { meta?: { __raw?: string } };
+}
+
+/** The `<pre>` hast node a Shiki `pre` hook receives. */
+interface PreNode {
+  properties: Record<string, boolean | number | string | undefined>;
+}
+
+/** A Shiki-compatible transformer, typed structurally to avoid a Shiki dep. */
+export interface CodeTitleTransformer {
+  name: string;
+  pre: (this: CodeMetaContext, node: PreNode) => void;
+}
+
+const TITLE_ATTR = /title=(?<quote>["'])(?<title>[^"']*)\k<quote>/u;
+const LINE_NUMBERS = /(?:^|\s)lineNumbers(?=\s|$)/u;
+
+const parseTitle = (raw: string | undefined): string | undefined => {
+  if (!raw) {
+    return undefined;
+  }
+  const explicit = raw.match(TITLE_ATTR);
+  if (explicit?.groups?.title) {
+    return explicit.groups.title;
+  }
+  // The first bare token is the title (```ts blume.config.ts), skipping Shiki
+  // line ranges (`{1,3-5}`), `key=value` attrs, and the reserved `lineNumbers`
+  // and `twoslash` keywords.
+  return raw
+    .trim()
+    .split(/\s+/u)
+    .find(
+      (token) =>
+        token.length > 0 &&
+        token !== "lineNumbers" &&
+        token !== "twoslash" &&
+        !token.startsWith("{") &&
+        !token.includes("=")
+    );
+};
+
+const hasLineNumbers = (raw: string | undefined): boolean =>
+  Boolean(raw && LINE_NUMBERS.test(raw));
+
+/** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
+export const codeTitleTransformer = (): CodeTitleTransformer => ({
+  name: "blume:code-meta",
+  pre(node) {
+    const raw = this.options.meta?.__raw;
+    const title = parseTitle(raw);
+    if (title) {
+      node.properties.dataTitle = title;
+    }
+    if (hasLineNumbers(raw)) {
+      node.properties.dataLineNumbers = true;
+    }
+  },
+});