npm - blume - Versions diffs - 0.1.4 → 0.2.0 - Mend

blume 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/dist/cli/index.js +359 -152
package/dist/cli/index.js.map +11 -9
package/dist/types/core/schema.d.ts +110 -6
package/docs/advanced/changelog.mdx +28 -1
package/docs/advanced/custom-pages.mdx +0 -1
package/docs/configuration/index.mdx +12 -11
package/docs/configuration/search.mdx +13 -1
package/docs/configuration/theming.mdx +51 -0
package/docs/content/components.mdx +18 -0
package/docs/content/navigation.mdx +8 -2
package/docs/content/sources.mdx +43 -0
package/docs/content/syntax.mdx +1 -1
package/docs/index.mdx +1 -1
package/docs/reference/cli.mdx +7 -1
package/docs/reference/frontmatter.mdx +9 -1
package/package.json +1 -1
package/src/astro/generate.ts +30 -13
package/src/astro/templates.ts +10 -1
package/src/cli/env.ts +84 -0
package/src/cli/index.ts +5 -0
package/src/cli/prepare.ts +5 -0
package/src/components/content/CodeBlock.astro +7 -2
package/src/components/layout/nav-utils.ts +50 -6
package/src/core/schema.ts +26 -0
package/src/core/sources/github-releases.ts +200 -0
package/src/core/sources/resolve.ts +16 -0
package/src/markdown/index.ts +24 -0
package/docs/changelog/v0-1-0.mdx +0 -12
package/docs/changelog/v0-2-0.mdx +0 -16

package/src/cli/env.ts ADDED Viewed

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "pathe";
+// Blume's remote sources (GitHub Releases, mdx-remote, Sanity, Notion…) read
+// their tokens from `process.env` during the content scan — which runs before
+// Astro/Vite boots, so Vite's own `.env` loading is too late. This loader fills
+// that gap: it cascades `.env`/`.env.local` from the working dir up to the repo
+// root, so a monorepo can keep one `.env` at the root and every app picks it up.
+const ENV_LINE =
+  /^\s*(?:export\s+)?(?<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?<value>.*?)\s*$/u;
+const DOUBLE_QUOTED = /^"(?<body>[\s\S]*)"$/u;
+const SINGLE_QUOTED = /^'(?<body>[\s\S]*)'$/u;
+/** Unquote a value, expanding `\n`/`\t`/escapes inside double quotes only. */
+const unquote = (raw: string): string => {
+  const double = raw.match(DOUBLE_QUOTED)?.groups?.body;
+  if (double !== undefined) {
+    return double
+      .replaceAll("\\n", "\n")
+      .replaceAll("\\t", "\t")
+      .replaceAll('\\"', '"')
+      .replaceAll("\\\\", "\\");
+  }
+  const single = raw.match(SINGLE_QUOTED)?.groups?.body;
+  if (single !== undefined) {
+    return single;
+  }
+  return raw;
+};
+/** Parse `.env` text into key/value pairs, skipping blanks and `#` comments. */
+export const parseEnv = (content: string): Record<string, string> => {
+  const env: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/u)) {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) {
+      continue;
+    }
+    const groups = line.match(ENV_LINE)?.groups;
+    if (groups?.key !== undefined && groups.value !== undefined) {
+      env[groups.key] = unquote(groups.value);
+    }
+  }
+  return env;
+};
+/** Apply parsed vars without clobbering anything already in `process.env`. */
+const applyEnv = (parsed: Record<string, string>): void => {
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!(key in process.env)) {
+      process.env[key] = value;
+    }
+  }
+};
+const loadFile = (path: string): void => {
+  try {
+    if (existsSync(path)) {
+      applyEnv(parseEnv(readFileSync(path, "utf-8")));
+    }
+  } catch {
+    // Env files are best-effort; a read/parse failure must not abort a build.
+  }
+};
+/**
+ * Load `.env`/`.env.local`, cascading from `startDir` up to the repository root
+ * (the first ancestor containing a `.git`) or the filesystem root. Nearer files
+ * and existing `process.env` values win, so shell/CI overrides are never lost
+ * and `.env.local` layers over `.env`.
+ */
+export const loadEnvFiles = (startDir: string): void => {
+  let dir = resolve(startDir);
+  let done = false;
+  while (!done) {
+    loadFile(join(dir, ".env.local"));
+    loadFile(join(dir, ".env"));
+    const parent = dirname(dir);
+    // Stop at the repo root (nearest `.git`) or the filesystem root.
+    done = existsSync(join(dir, ".git")) || parent === dir;
+    dir = parent;
+  }
+};

package/src/cli/index.ts CHANGED Viewed

@@ -11,6 +11,7 @@ import { migrateCommand } from "./commands/migrate.ts";
 import { previewCommand } from "./commands/preview.ts";
 import { syncCommand } from "./commands/sync.ts";
 import { validateCommand } from "./commands/validate.ts";
+import { loadEnvFiles } from "./env.ts";
 const main = defineCommand({
   meta: {
@@ -32,4 +33,8 @@ const main = defineCommand({
   },
 });
+// Load `.env`/`.env.local` before any command runs so remote content sources
+// can read their tokens (e.g. `GITHUB_TOKEN`) during the content scan.
+loadEnvFiles(process.cwd());
 runMain(main);

package/src/cli/prepare.ts CHANGED Viewed

@@ -3,6 +3,7 @@ import { BlumeError, hasErrors } from "../core/diagnostics.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject, BuildMode } from "../core/project-graph.ts";
 import { serverFeatures } from "../core/server-features.ts";
+import { loadEnvFiles } from "./env.ts";
 import { logger, reportDiagnostics } from "./log.ts";
 export interface PrepareOptions {
@@ -24,6 +25,10 @@ export interface PrepareOptions {
 export const prepareProject = async (
   options: PrepareOptions
 ): Promise<BlumeProject> => {
+  // Honor a `--root` that differs from cwd: remote sources read env during the
+  // scan below, and `loadEnvFiles` is a no-op for vars already set (cwd load).
+  loadEnvFiles(options.root);
   let project: BlumeProject;
   try {
     project = await scanProject(options.root, {

package/src/components/content/CodeBlock.astro CHANGED Viewed

@@ -19,10 +19,15 @@ interface Props {
   lang?: string;
   /** Show the brand language icon in the header (default on, like fences). */
   icons?: boolean;
+  /** Header title (a filename); falls back to the language label like fences. */
+  title?: string;
 }
-const { code, lang = "txt", icons } = Astro.props;
-const html = await highlightCode(code.replace(/\n+$/u, ""), lang, { icons });
+const { code, lang = "txt", icons, title } = Astro.props;
+const html = await highlightCode(code.replace(/\n+$/u, ""), lang, {
+  icons,
+  title,
+});
 ---
 <div class="prose max-w-none"><Fragment set:html={html} /></div>

package/src/components/layout/nav-utils.ts CHANGED Viewed

@@ -114,13 +114,56 @@ const sectionChildren = (nodes: NavNode[], base: string): NavNode[] | null => {
   return null;
 };
+/** Whether a group maps to a header tab (matched on its path or link route). */
+const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean =>
+  node.kind === "group" &&
+  ((node.path !== undefined && tabPaths.has(node.path)) ||
+    (node.route !== undefined && tabPaths.has(node.route)));
+/**
+ * Drop the groups that already own a header tab from the tree, at any depth —
+ * so a root/un-tabbed route lists only the pages outside every tab's section
+ * instead of duplicating each tab as a sidebar group. A container left empty by
+ * this pruning is dropped too, so no bare heading is stranded. The root tab
+ * (`/`) spans everything, so it never removes anything.
+ */
+const withoutTabSections = (nodes: NavNode[], tabs: NavTab[]): NavNode[] => {
+  const tabPaths = new Set(
+    tabs.filter((tab) => tab.path !== "/").map((tab) => tab.path)
+  );
+  if (tabPaths.size === 0) {
+    return nodes;
+  }
+  const prune = (items: NavNode[]): NavNode[] => {
+    const kept: NavNode[] = [];
+    for (const item of items) {
+      if (isTabSection(item, tabPaths)) {
+        continue;
+      }
+      if (item.kind === "group") {
+        const children = prune(item.children);
+        if (children.length === 0) {
+          continue;
+        }
+        kept.push({ ...item, children });
+      } else {
+        kept.push(item);
+      }
+    }
+    return kept;
+  };
+  return prune(nodes);
+};
 /**
  * Scope the sidebar to the active tab's section. With tabs configured, a route
  * under one tab shows only that tab's group — so a multi-section site (e.g.
  * Adapters / API / AI tabs) drills each tab into its own pages instead of one
- * global tree, the way Fumadocs' root folders do. Falls back to the full
- * sidebar when no tab matches (or the tab maps to no group), so a route is
- * never left with a blank sidebar.
+ * global tree, the way Fumadocs' root folders do. On a route under no tab (or
+ * the root `/` tab), the tab-owned groups are hidden so the root sidebar shows
+ * only pages that don't belong to a tab. Falls back to the full sidebar when a
+ * matched tab maps to no group, or when hiding the tab sections would blank the
+ * sidebar, so a route is never left empty.
  */
 export const sidebarForRoute = (
   sidebar: NavNode[],
@@ -128,10 +171,11 @@ export const sidebarForRoute = (
   route: string
 ): NavNode[] => {
   const tab = activeTab(tabs, route);
-  if (!tab) {
-    return sidebar;
+  if (tab) {
+    return sectionChildren(sidebar, tab.path) ?? sidebar;
   }
-  return sectionChildren(sidebar, tab.path) ?? sidebar;
+  const scoped = withoutTabSections(sidebar, tabs);
+  return scoped.length > 0 ? scoped : sidebar;
 };
 /** Resolve previous/next pages around the current route. */

package/src/core/schema.ts CHANGED Viewed

@@ -283,6 +283,31 @@ const notionSourceSchema = z.object({
   type: z.literal("notion"),
 });
+/**
+ * A repo's GitHub Releases, materialized as `type: changelog` entries — release
+ * notes become the changelog with no files to maintain. A private repo reads a
+ * token from `GITHUB_TOKEN`; it is never inlined here.
+ */
+const githubReleasesSourceSchema = z
+  .object({
+    /** Include draft releases (needs a token with repo write access). */
+    drafts: z.boolean().optional(),
+    /** Cap the number of releases materialized, newest-first. Default 100. */
+    limit: z.number().positive().optional(),
+    /** Repository owner (user or org). */
+    owner: z.string(),
+    /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+    pollInterval: z.number().positive().optional(),
+    /** Namespaces the source's routes under `/<prefix>/`; e.g. `changelog`. */
+    prefix: z.string().optional(),
+    /** Include prereleases. */
+    prereleases: z.boolean().optional(),
+    /** Repository name. */
+    repo: z.string(),
+    type: z.literal("github-releases"),
+  })
+  .strict();
 /**
  * In-place Mintlify content (`docs.json` + MDX). Powers "bridge mode": Blume
  * reads an unconverted Mintlify project, transforming each page to Blume MDX at
@@ -328,6 +353,7 @@ const customSourceSchema = z.object({
 const contentSourceSchema = z.discriminatedUnion("type", [
   filesystemSourceSchema,
   mdxRemoteSourceSchema,
+  githubReleasesSourceSchema,
   sanitySourceSchema,
   notionSourceSchema,
   mintlifySourceSchema,

package/src/core/sources/github-releases.ts ADDED Viewed

@@ -0,0 +1,200 @@
+import matter from "../frontmatter.ts";
+import {
+  hashText,
+  loadWithCache,
+  pollingWatch,
+  snapshotCache,
+} from "./cache.ts";
+import type {
+  ContentSource,
+  SourceContext,
+  SourceEntry,
+  SourceLoadResult,
+} from "./types.ts";
+/** Options for the built-in GitHub Releases changelog source. */
+export interface GithubReleasesSourceOptions {
+  /** GitHub REST API base; overridable for GitHub Enterprise / tests. */
+  baseUrl?: string;
+  /** Include draft releases (needs a token with repo write access). Default off. */
+  drafts?: boolean;
+  /** Injected for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Cap the number of releases materialized, newest-first. Default 100. */
+  limit?: number;
+  name: string;
+  /** Repository owner (user or org). */
+  owner: string;
+  /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
+  pollInterval?: number;
+  /** Namespaces the source's routes under `/<prefix>/`; e.g. `changelog`. */
+  prefix?: string;
+  /** Include prereleases. Default off. */
+  prereleases?: boolean;
+  /** Repository name. */
+  repo: string;
+}
+/** The subset of the GitHub release payload the adapter reads. */
+interface GithubRelease {
+  body: string | null;
+  created_at: string;
+  draft: boolean;
+  html_url: string;
+  id: number;
+  name: string | null;
+  prerelease: boolean;
+  published_at: string | null;
+  tag_name: string;
+}
+const DEFAULT_BASE_URL = "https://api.github.com";
+const DEFAULT_LIMIT = 100;
+const PER_PAGE = 100;
+const LEADING_V = /^v/iu;
+const NON_SLUG = /[^a-z0-9]+/gu;
+const EDGE_DASHES = /^-+|-+$/gu;
+/** Slugify a tag into a stable, URL-safe source ref (`v1.2.0` -> `v1-2-0`). */
+const slugifyTag = (tag: string): string =>
+  tag.toLowerCase().replaceAll(NON_SLUG, "-").replaceAll(EDGE_DASHES, "");
+/** Build request headers, reading `GITHUB_TOKEN` fresh at call time. */
+const githubHeaders = (): Headers => {
+  const headers = new Headers({ Accept: "application/vnd.github+json" });
+  const token = process.env.GITHUB_TOKEN;
+  if (token) {
+    headers.set("Authorization", `Bearer ${token}`);
+  }
+  return headers;
+};
+/**
+ * Lower one release to a staged Markdown entry: the notes become the body and
+ * `type: changelog` frontmatter (title/date/version/category) drives the
+ * generated `/changelog` timeline and RSS feed.
+ */
+const releaseToEntry = (release: GithubRelease): SourceEntry => {
+  const version = release.tag_name.replace(LEADING_V, "");
+  const title = release.name?.trim() || release.tag_name;
+  const date = release.published_at ?? release.created_at;
+  const category = release.prerelease ? "Prerelease" : "Release";
+  const body = (release.body ?? "").replaceAll("\r\n", "\n").trim();
+  const data = {
+    changelog: { category, version },
+    date,
+    title,
+    type: "changelog",
+  };
+  const raw = matter.stringify(`${body}\n`, data);
+  const ref = `${slugifyTag(release.tag_name) || `release-${release.id}`}.md`;
+  return {
+    body: { format: "md", text: body },
+    data,
+    editUrl: release.html_url,
+    hash: hashText(raw),
+    lastModified: date,
+    raw,
+    ref,
+  };
+};
+/**
+ * GitHub Releases content source. Pulls a repo's releases from the REST API and
+ * materializes each as a `type: changelog` entry, so a project's release notes
+ * become its changelog with no files to maintain. A private repo authenticates
+ * with `GITHUB_TOKEN`. A snapshot under `.blume/cache/<source>/` keeps rebuilds
+ * offline-tolerant.
+ */
+export const githubReleasesSource = (
+  options: GithubReleasesSourceOptions,
+  ctx: SourceContext
+): ContentSource => {
+  const doFetch = options.fetchImpl ?? globalThis.fetch;
+  const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/u, "");
+  const max = options.limit ?? DEFAULT_LIMIT;
+  const cache = snapshotCache(ctx.cacheDir);
+  let snapshot = new Map<string, SourceEntry>();
+  const include = (release: GithubRelease): boolean =>
+    (options.drafts || !release.draft) &&
+    (options.prereleases || !release.prerelease);
+  const fetchPage = async (page: number): Promise<GithubRelease[]> => {
+    const url = `${base}/repos/${options.owner}/${options.repo}/releases?per_page=${PER_PAGE}&page=${page}`;
+    const res = await doFetch(url, { headers: githubHeaders() });
+    if (!res.ok) {
+      throw new Error(`${url} -> ${res.status}`);
+    }
+    return (await res.json()) as GithubRelease[];
+  };
+  const fetchReleases = async (): Promise<GithubRelease[]> => {
+    const collected: GithubRelease[] = [];
+    let page = 1;
+    while (collected.length < max) {
+      // oxlint-disable-next-line no-await-in-loop -- pages are sequential: each page's length decides whether another exists.
+      const batch = await fetchPage(page);
+      collected.push(...batch.filter(include));
+      if (batch.length < PER_PAGE) {
+        break;
+      }
+      page += 1;
+    }
+    return collected.slice(0, max);
+  };
+  const load = async (): Promise<SourceLoadResult> => {
+    try {
+      const result = await loadWithCache(
+        options.name,
+        cache,
+        async () => {
+          const releases = await fetchReleases();
+          return releases.map(releaseToEntry);
+        },
+        ctx.refresh ?? true
+      );
+      snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
+      return result;
+    } catch (error) {
+      // A changelog is supplementary. When releases can't be fetched and nothing
+      // is cached (e.g. CI or a deploy without a `GITHUB_TOKEN` for a private
+      // repo), degrade to an empty changelog with a warning rather than failing
+      // the whole build.
+      snapshot = new Map();
+      return {
+        diagnostics: [
+          {
+            code: "BLUME_SOURCE_UNAVAILABLE",
+            message: `Source "${options.name}" could not fetch GitHub releases (${(error as Error).message}); the changelog will be empty. Set GITHUB_TOKEN to include it (required for a private repository).`,
+            severity: "warning",
+          },
+        ],
+        entries: [],
+      };
+    }
+  };
+  const read = async (ref: string): Promise<string> => {
+    const cached = snapshot.get(ref);
+    if (cached) {
+      return cached.raw ?? cached.body.text;
+    }
+    const all = await cache.read();
+    const entry = all.find((e) => e.ref === ref);
+    return entry?.raw ?? entry?.body.text ?? "";
+  };
+  return {
+    load,
+    name: options.name,
+    prefix: options.prefix,
+    read,
+    staged: true,
+    watch: options.pollInterval
+      ? pollingWatch(load, options.pollInterval)
+      : undefined,
+  };
+};

package/src/core/sources/resolve.ts CHANGED Viewed

@@ -3,6 +3,7 @@ import { join } from "pathe";
 import type { ContentSourceConfig, ResolvedConfig } from "../schema.ts";
 import type { ProjectContext } from "../types.ts";
 import { filesystemSource } from "./filesystem.ts";
+import { githubReleasesSource } from "./github-releases.ts";
 import { mdxRemoteSource } from "./mdx-remote.ts";
 import { mintlifySource } from "./mintlify.ts";
 import { notionSource } from "./notion.ts";
@@ -106,6 +107,21 @@ const buildSource = (
       sourceContext(context, name, runtime)
     );
   }
+  if (def.type === "github-releases") {
+    return githubReleasesSource(
+      {
+        drafts: def.drafts,
+        limit: def.limit,
+        name,
+        owner: def.owner,
+        pollInterval: def.pollInterval,
+        prefix: def.prefix,
+        prereleases: def.prereleases,
+        repo: def.repo,
+      },
+      sourceContext(context, name, runtime)
+    );
+  }
   return mdxRemoteSource(
     {
       files: def.files,

package/src/markdown/index.ts CHANGED Viewed

@@ -128,9 +128,26 @@ const astroCodeClassTransformer = (extra?: string): ShikiTransformer =>
     },
   }) as unknown as ShikiTransformer;
+/**
+ * Tag the `<pre>` with `data-language` — raw `codeToHtml` omits it (unlike
+ * Astro's Markdown Shiki), and the theme's code header keys off it. Applied only
+ * on the titled path so a titled standalone block renders the same header bar a
+ * fence would, while header-less panes (e.g. the Component source view) stay
+ * untouched.
+ */
+const languageAttrTransformer = (lang: string): ShikiTransformer =>
+  ({
+    name: "blume:data-language",
+    pre(node: { properties: Record<string, unknown> }) {
+      node.properties.dataLanguage ??= lang;
+    },
+  }) as unknown as ShikiTransformer;
 export interface HighlightCodeOptions extends BlumeShikiOptions {
   /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
   className?: string;
+  /** Header title (a filename), matching a fence's `title="..."` meta. */
+  title?: string;
 }
 /**
@@ -152,10 +169,17 @@ export const highlightCode = async (
     return await codeToHtml(code, {
       defaultColor: false,
       lang,
+      // The code-title transformer reads the fence meta; feeding a `title="..."`
+      // string here gives non-fence callers (e.g. `<CodeBlock title>`) the same
+      // `data-title` header a Markdown fence gets.
+      meta: options.title
+        ? { __raw: `title="${options.title.replaceAll('"', "")}"` }
+        : undefined,
       themes: CODE_THEMES,
       transformers: [
         ...blumeShikiTransformers({ icons: options.icons }),
         astroCodeClassTransformer(options.className),
+        ...(options.title ? [languageAttrTransformer(lang)] : []),
       ],
     });
   } catch {

package/docs/changelog/v0-1-0.mdx DELETED Viewed

@@ -1,12 +0,0 @@
----
-title: v0.1.0
-type: changelog
-date: 2026-06-01
-changelog:
-  version: 0.1.0
-  category: Release
----
-The first public release of Blume — a markdown-first docs framework on Astro and
-Vite. Drop in Markdown or MDX, run `blume dev`, and ship a production-grade docs
-site with search, theming, and AI-ready output.

package/docs/changelog/v0-2-0.mdx DELETED Viewed

@@ -1,16 +0,0 @@
----
-title: v0.2.0
-type: changelog
-date: 2026-06-24
-changelog:
-  version: 0.2.0
-  category: Features
----
-A big batch of built-in components landed: **columns**, **frames**, **trees**,
-**tooltips**, **code groups**, **panels**, **tiles**, and **fields**. Code groups
-now render as proper language tabs, and the changelog gets this timeline.
-- New `Accordion` / `AccordionItem`, `Expandable`, `Tooltip`, `Frame`, `Color`
-- `CodeGroup` tabs with flush code blocks
-- Redesigned `Prompt` with a copy-to-clipboard button