blume 0.0.0 → 0.1.0

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,27 @@
+export { defineConfig } from "./core/config.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 {
+  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;
+    }
+  },
+});

package/src/markdown/directives.ts

@@ -0,0 +1,83 @@
+import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+
+interface DirectiveNode extends MdastNode {
+  attributes?: Record<string, string | null | undefined> | null;
+  children: MdastNode[];
+  name: string;
+}
+
+/** Directive names that map directly onto a Callout type. */
+const CALLOUT_TYPES = new Set([
+  "danger",
+  "info",
+  "note",
+  "success",
+  "tip",
+  "warning",
+]);
+
+/** Friendly aliases for the canonical Callout types. */
+const ALIASES: Record<string, string> = {
+  caution: "warning",
+  error: "danger",
+  important: "note",
+  warn: "warning",
+};
+
+/** Resolve a directive name to a Callout type, or `null` if it is not one. */
+export const calloutTypeFor = (name: string): string | null => {
+  const lower = name.toLowerCase();
+  if (CALLOUT_TYPES.has(lower)) {
+    return lower;
+  }
+  return ALIASES[lower] ?? null;
+};
+
+interface TextNode extends MdastNode {
+  value?: string;
+}
+
+/** Concatenate the plain text of a node's immediate phrasing children. */
+const textOf = (node: MdastNode): string =>
+  ((node.children as TextNode[] | undefined) ?? [])
+    .map((child) => child.value ?? "")
+    .join("");
+
+/**
+ * Satteri MDAST plugin mapping container directives (`:::note`, `:::warning`,
+ * `:::tip`, …) onto Blume's `<Callout>` component. The title comes from a
+ * `[label]` or a `{title="…"}` attribute; the body becomes the callout content.
+ * Directive names that are not callouts are left untouched.
+ */
+export const directiveToCalloutPlugin = () => ({
+  containerDirective(node: DirectiveNode, ctx: MdastVisitorContext) {
+    const type = calloutTypeFor(node.name);
+    if (type === null) {
+      return;
+    }
+
+    const children = [...node.children];
+    let title = node.attributes?.title ?? undefined;
+
+    // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.
+    const labelIndex = children.findIndex(
+      (child) =>
+        child.type === "paragraph" &&
+        (child.data as { directiveLabel?: boolean } | undefined)?.directiveLabel
+    );
+    if (labelIndex !== -1) {
+      const [label] = children.splice(labelIndex, 1);
+      if (label) {
+        title ??= textOf(label) || undefined;
+      }
+    }
+
+    const attributes = [jsxAttribute("type", type)];
+    if (title) {
+      attributes.push(jsxAttribute("title", title));
+    }
+    ctx.replaceNode(node, jsxFlowElement("Callout", attributes, children));
+  },
+  name: "blume-directive-callout",
+});

package/src/markdown/heading-anchors.ts

@@ -0,0 +1,137 @@
+/**
+ * Turn every section heading into its own permalink. A Satteri hast plugin runs
+ * after Markdown is turned into hast and wraps each `<h2>`–`<h6>`'s content in an
+ * `<a href="#slug">`, so a reader can click the heading to copy, bookmark, or
+ * share a link straight to that section. `<h1>` (the page title) is slugged for
+ * parity but left unwrapped.
+ *
+ * Satteri's own `heading-ids` plugin (which assigns the `id` used by the table
+ * of contents) runs *after* every user hast plugin, and it reuses an `id` that
+ * is already present rather than re-slugging. So this plugin is the authoritative
+ * id setter: it slugs each heading with the same algorithm (a per-document
+ * `github-slugger`, the library Satteri and rehype-slug both use) and writes the
+ * `id`, which `heading-ids` then adopts — keeping the in-page anchor, the
+ * heading's `id`, and the TOC entry in lockstep. To match Satteri's duplicate
+ * disambiguation (`setup`, `setup-1`, …) exactly, it advances the slugger over
+ * `<h1>`–`<h6>` in document order even though only `<h2>`–`<h6>` get wrapped.
+ */
+
+import { satteriCollectHastText } from "@astrojs/markdown-satteri";
+import GithubSlugger from "github-slugger";
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  name?: string;
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  type: string;
+  value?: string;
+}
+
+/** The slice of Satteri's hast visitor context this plugin reads. */
+interface HastContext {
+  data?: { astro?: { frontmatter?: Record<string, unknown> } };
+  setProperty: (node: HastNode, key: string, value: unknown) => void;
+  textContent: (node: HastNode) => string;
+}
+
+/** A Satteri hast plugin, typed structurally to avoid a Satteri dep. */
+export interface HeadingAnchorPlugin {
+  name: string;
+  element: {
+    filter: string[];
+    visit: (node: HastNode, ctx: HastContext) => HastNode | undefined;
+  };
+}
+
+/** Headings slugged for id parity with Satteri; only a subset gets wrapped. */
+const HEADINGS = ["h1", "h2", "h3", "h4", "h5", "h6"];
+const WRAPPED = new Set(["h2", "h3", "h4", "h5", "h6"]);
+
+/** True if the subtree already contains an `<a>`, so wrapping would nest links. */
+const containsAnchor = (node: HastNode): boolean => {
+  for (const child of node.children ?? []) {
+    if ((child.tagName ?? child.name) === "a" || containsAnchor(child)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+// One slugger per document render. The plugin instance is shared across every
+// page, but slug disambiguation must reset per document; the render-scoped
+// `astro` data object is a stable, unique key for one render (entries are
+// dropped once the render is collected, so this never leaks).
+const FALLBACK_SCOPE: object = {};
+const sluggers = new WeakMap<object, GithubSlugger>();
+
+const sluggerFor = (ctx: HastContext): GithubSlugger => {
+  const scope = ctx.data?.astro ?? ctx.data ?? FALLBACK_SCOPE;
+  const existing = sluggers.get(scope);
+  if (existing) {
+    return existing;
+  }
+  const slugger = new GithubSlugger();
+  sluggers.set(scope, slugger);
+  return slugger;
+};
+
+/** The slug for a heading, mirroring Satteri's `heading-ids` exactly. */
+const slugFor = (
+  node: HastNode,
+  ctx: HastContext,
+  slugger: GithubSlugger
+): string => {
+  const rawText = ctx.textContent(node);
+  // `frontmatter`-interpolated MDX headings (`## {frontmatter.title}`) need the
+  // resolved value; the helper is the same one `heading-ids` defers to.
+  const text = rawText.includes("frontmatter")
+    ? satteriCollectHastText(
+        node as Parameters<typeof satteriCollectHastText>[0],
+        ctx.data?.astro?.frontmatter ?? {}
+      )
+    : rawText;
+  const existingId = node.properties?.id;
+  return typeof existingId === "string" ? existingId : slugger.slug(text);
+};
+
+/** Build the plugin. Wraps `<h2>`–`<h6>` in self-linking anchors. */
+export const headingAnchorPlugin = (): HeadingAnchorPlugin => ({
+  element: {
+    filter: HEADINGS,
+    visit(node, ctx) {
+      const slug = slugFor(node, ctx, sluggerFor(ctx));
+      const wrap = node.tagName
+        ? WRAPPED.has(node.tagName) && slug !== "" && !containsAnchor(node)
+        : false;
+      if (!wrap) {
+        // Unwrapped headings (h1, an empty slug, or one that already links) still
+        // need the id so `heading-ids` adopts it instead of re-slugging.
+        if (typeof node.properties?.id !== "string") {
+          ctx.setProperty(node, "id", slug);
+        }
+        return;
+      }
+      // Replacing the heading re-emits its original children as refs inside the
+      // new anchor (Satteri passes reused nodes through untouched).
+      return {
+        children: [
+          {
+            children: node.children ?? [],
+            properties: {
+              className: ["blume-heading-anchor"],
+              href: `#${slug}`,
+            },
+            tagName: "a",
+            type: "element",
+          },
+        ],
+        properties: { ...node.properties, id: slug },
+        tagName: node.tagName,
+        type: "element",
+      };
+    },
+  },
+  name: "blume:heading-anchors",
+});