blume 1.5.3 → 1.6.1

package/src/core/schema.ts

@@ -7,11 +7,21 @@ import { normalizeRoute } from "../openapi/references.ts";
 import { normalizeXHandle } from "../seo/x-handle.ts";
 import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
 import { normalizeBasePath } from "./base-path.ts";
+import { PUBLIC_HOST_URL } from "./github.ts";
 import { uiLocaleOverridesSchema } from "./i18n-ui.ts";
 import { openInChatProviders } from "./open-in-chat.ts";
 import type { ContentSource } from "./sources/types.ts";
 import { isStandardSchema } from "./standard-schema.ts";
 import type { StandardSchema } from "./standard-schema.ts";
+import { trimEnd } from "./trim.ts";
+
+/**
+ * An absolute HTTP(S) URL, for any field that lands verbatim in an `href` —
+ * the header repo mark, the GitHub instance origin. Zod's bare `z.url()` also
+ * admits `javascript:` and `data:`, which would render as a script link on
+ * every page.
+ */
+const httpUrlSchema = z.url({ protocol: /^https?$/u });
 
 /**
  * Public Blume schemas.
@@ -347,6 +357,21 @@ const notionSourceSchema = z.object({
   type: z.literal("notion"),
 });
 
+/**
+ * An Obsidian vault, read in place. Wikilinks become route links and
+ * `%%comments%%` are stripped at load time, so the vault stays the source of
+ * truth — no export step and no generated notes in the repo.
+ */
+const obsidianSourceSchema = z.strictObject({
+  /** Vault folder names to skip at any depth, in addition to dot-folders. */
+  exclude: z.array(z.string()).optional(),
+  /** Namespaces the source's routes under `/<prefix>/`; e.g. `vault`. */
+  prefix: z.string().optional(),
+  type: z.literal("obsidian"),
+  /** Vault directory, absolute or relative to the project root. */
+  vault: z.string().min(1),
+});
+
 /**
  * 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
@@ -396,6 +421,7 @@ const contentSourceSchema = z.discriminatedUnion("type", [
   githubReleasesSourceSchema,
   sanitySourceSchema,
   notionSourceSchema,
+  obsidianSourceSchema,
   customSourceSchema,
 ]);
 
@@ -547,6 +573,8 @@ const remoteFontSchema = z.strictObject({
   provider: z
     .enum(["google", "fontsource", "bunny", "fontshare"])
     .default("google"),
+  /** Character subsets to load; defaults to `latin` plus the locales' scripts. */
+  subsets: z.array(z.string().min(1)).nonempty().optional(),
   weights: z
     .array(
       z.union([z.number().int().positive(), z.string().regex(/^\d+\.\.\d+$/u)])
@@ -693,6 +721,7 @@ const searchConfigSchema = z
     algolia: algoliaSearchSchema.optional(),
     indexing: z
       .strictObject({
+        includeCodeBlocks: z.boolean().default(false),
         includeHiddenPages: z.boolean().default(false),
       })
       .prefault({}),
@@ -794,6 +823,20 @@ const askEndpointSchema = z
     }
   );
 
+/** The object form of `ai.llmsTxt`; a bare boolean normalizes onto it. */
+const llmsTxtObjectSchema = z.strictObject({
+  /**
+   * Markdown inserted after the title and summary, before the page sections:
+   * the llms.txt spec's "details" slot. The place to tell agents when to use
+   * the product and how to call it; trimmed, and dropped when blank.
+   */
+  details: z.string().trim().min(1).optional(),
+  enabled: z.boolean().default(true),
+  openapi: z.boolean().default(true),
+});
+
+type LlmsTxtResolved = z.output<typeof llmsTxtObjectSchema>;
+
 const aiConfigSchema = z.strictObject({
   ask: z
     .strictObject({
@@ -857,18 +900,14 @@ const aiConfigSchema = z.strictObject({
   /**
    * `llms.txt`/`llms-full.txt` emission. A bare boolean toggles it; the object
    * form adds `openapi: false` to keep generated API reference pages out of
-   * both files (e.g. when the configured spec is example content).
+   * both files (e.g. when the configured spec is example content) and
+   * `details`, free-form Markdown placed after the summary — the llms.txt
+   * spec's details block, where a site tells agents when to reach for it.
    */
   llmsTxt: z
-    .union([
-      z.boolean(),
-      z.strictObject({
-        enabled: z.boolean().default(true),
-        openapi: z.boolean().default(true),
-      }),
-    ])
+    .union([z.boolean(), llmsTxtObjectSchema])
     .default(true)
-    .transform((value) =>
+    .transform((value): LlmsTxtResolved =>
       isBoolean(value) ? { enabled: value, openapi: true } : value
     ),
   // Serializers for the agent-facing Markdown downlevel (the `.md` mirror,
@@ -954,11 +993,37 @@ const featuredLinkSchema = z.strictObject({
   label: z.string(),
 });
 
+/**
+ * A header link: a plain one (`Log in`, `Status`), or the single call to
+ * action. Same shape as a featured link minus the icon — the header row is
+ * text, not iconography.
+ */
+const headerActionSchema = z.strictObject({
+  href: z.string(),
+  label: z.string(),
+});
+
 const navigationConfigSchema = z.strictObject({
+  /** Plain links in the header, left of the icon buttons. */
+  actions: z.array(headerActionSchema).default([]),
+  /**
+   * The one primary call to action in the header, as a filled button.
+   *
+   * Singular on purpose: a docs header has room for exactly one thing a
+   * reader is being asked to do, a row of buttons asks for nothing, and
+   * `featured` already takes the secondary links.
+   */
+  cta: headerActionSchema.optional(),
   /** Pinned links shown above the generated sidebar sections. */
   featured: z.array(featuredLinkSchema).default([]),
-  /** Show a GitHub repo link in the header (requires `github` configured). */
-  repo: z.boolean().default(true),
+  /**
+   * The GitHub link in the header. `true` derives it from `github`, `false`
+   * hides it, and an absolute URL points it anywhere on GitHub — an
+   * organization, say, when the docs repo itself is private and `github` has
+   * to stay unset. The mark stays the GitHub one, so a URL elsewhere belongs in
+   * `actions`.
+   */
+  repo: z.union([z.boolean(), httpUrlSchema]).default(true),
   selectors: z.array(navSelectorSchema).default([]),
   /**
    * Sidebar behavior. `display` sets how every group renders (a group in an
@@ -1266,8 +1331,9 @@ const ogFontSchema = z.union([
 
 const ogConfigSchema = z.strictObject({
   /**
-   * Card subtitle. Defaults to the site description; a string overrides it,
-   * `false` renders the card without one.
+   * Site-wide card subtitle, shown on pages without their own description.
+   * Defaults to the site description; a string overrides it, `false` renders
+   * every card without a subtitle (page descriptions included).
    */
   description: z.union([z.string(), z.literal(false)]).optional(),
   /**
@@ -1346,6 +1412,50 @@ const contentSignalsSchema = z
     return value;
   });
 
+/** A schema.org `PostalAddress`, any part of which may be given. */
+const postalAddressSchema = z.strictObject({
+  addressCountry: z.string().optional(),
+  addressLocality: z.string().optional(),
+  addressRegion: z.string().optional(),
+  postalCode: z.string().optional(),
+  streetAddress: z.string().optional(),
+});
+
+/**
+ * `seo.organization`: the organization behind the site, emitted on every page
+ * as a schema.org `Organization` node (see `seo/jsonld.ts`). Name and URL
+ * default to the site's; contact details become a `ContactPoint`, the address
+ * a `PostalAddress` — what agents check to verify a business.
+ */
+const organizationConfigSchema = z.strictObject({
+  address: postalAddressSchema.optional(),
+  contactType: z.string().default("customer support"),
+  email: z.email().optional(),
+  logo: z.string().optional(),
+  name: z.string().optional(),
+  sameAs: z.array(z.url()).default([]),
+  telephone: z.string().optional(),
+  url: z.url().optional(),
+});
+
+/**
+ * `seo.software`: the product the site documents, emitted on the homepage as
+ * a schema.org `SoftwareApplication` node. `true` takes every default (name
+ * and description from the site, category `DeveloperApplication`).
+ */
+const softwareConfigSchema = z.strictObject({
+  applicationCategory: z.string().default("DeveloperApplication"),
+  description: z.string().optional(),
+  license: z.string().optional(),
+  name: z.string().optional(),
+  operatingSystem: z.string().optional(),
+  price: z.union([z.number().nonnegative(), z.string()]).optional(),
+  priceCurrency: z.string().default("USD"),
+  sameAs: z.array(z.url()).default([]),
+});
+
+type SoftwareResolved = z.output<typeof softwareConfigSchema>;
+
 /** Discoverability features: OG images, feeds, sitemap, structured data. */
 const seoConfigSchema = z.strictObject({
   /**
@@ -1357,21 +1467,59 @@ const seoConfigSchema = z.strictObject({
   /** robots.txt `Content-Signal` usage declaration (on by default). */
   contentSignals: contentSignalsSchema.prefault(true),
   og: ogConfigSchema.default({}),
+  /** The organization behind the site, as an `Organization` JSON-LD node. */
+  organization: organizationConfigSchema.optional(),
   /** Generate robots.txt (with a Sitemap reference when available). */
   robots: z.boolean().default(true),
   rss: rssConfigSchema.prefault({}),
   /** Generate sitemap.xml (requires deployment.site). */
   sitemap: z.boolean().default(true),
+  /** The documented product, as a homepage `SoftwareApplication` node. */
+  software: z
+    .union([z.boolean(), softwareConfigSchema])
+    .optional()
+    .transform((value): SoftwareResolved | undefined => {
+      if (value === true) {
+        return softwareConfigSchema.parse({});
+      }
+      return value === false ? undefined : value;
+    }),
   /** Emit schema.org JSON-LD in each page's <head>. */
   structuredData: z.boolean().default(true),
   /** X (Twitter) account attribution for share cards. */
   x: xConfigSchema.default({}),
 });
 
+/**
+ * The GitHub instance's origin, normalized. Repo, edit, and API URLs are all
+ * built by appending to this, so it is reduced to a bare origin: a trailing
+ * slash would double the separator, and a path, query, fragment, or embedded
+ * credentials would land in the middle of every generated link.
+ */
+const githubOriginSchema = httpUrlSchema.transform(
+  (value) => new URL(value).origin
+);
+
+/**
+ * A REST API base: an origin plus an optional path, since Enterprise Server
+ * serves the API from `/api/v3`. Anything past the path is dropped for the same
+ * reason the host is reduced — `/repos/{owner}/{repo}` is appended as a string,
+ * so a query would swallow the route and a fragment would strip it from the
+ * request entirely, leaving a lookup that silently returns the wrong thing.
+ */
+const githubApiSchema = httpUrlSchema.transform((value) => {
+  const { origin, pathname } = new URL(value);
+  return trimEnd(`${origin}${pathname}`, "/");
+});
+
 const githubConfigSchema = z.strictObject({
+  /** REST API base. Derived from `host` when unset. */
+  api: githubApiSchema.optional(),
   branch: z.string().default("main"),
   /** Path from the repo root to the project root (for monorepos). */
   dir: z.string().optional(),
+  /** Origin of the GitHub instance, for Enterprise installations. */
+  host: githubOriginSchema.default(PUBLIC_HOST_URL),
   owner: z.string(),
   repo: z.string(),
 });
@@ -1560,6 +1708,14 @@ const openapiSourceSchema = z.strictObject({
   noindex: z.boolean().default(false),
   /** Per-source route; defaults to the block's `route` (or a derived path). */
   route: z.string().optional(),
+  /**
+   * Append the English "Reference for the … endpoint in the … API." sentence
+   * to every generated operation page's meta description. On by default, so
+   * terse specs still ship distinct, snippet-length descriptions; set to
+   * `false` on a non-English site to describe pages with the spec's own prose
+   * alone (falling back to the page title when an operation has none).
+   */
+  seoDescriptionSuffix: z.boolean().default(true),
   /** Local path or `http(s)` URL to the spec. */
   spec: z.string(),
 });
@@ -1577,9 +1733,33 @@ export type OpenApiSource = z.input<typeof openapiSourceSchema>;
 const scalarConfigSchema = z.record(z.string(), z.unknown()).optional();
 
 /**
- * The shared shape of both API-reference blocks — only the mount route and
+ * The interactive "Try it" panel on operation pages (Blume renderer). On by
+ * default; `false` hides it. The object form keeps it on and sets `proxy`,
+ * the CORS escape hatch the Send button routes requests through: a proxy URL,
+ * or `true` for the built-in `/_api-proxy` endpoint (which requires
+ * `deployment.output: "server"`). Booleans normalize to the object shape so
+ * consumers read `{ enabled, proxy }` directly. `proxy` applies to the
+ * HTTP-posting playgrounds (OpenAPI, GraphQL) — an event composer's WebSocket
+ * connect is direct. One schema for every reference block, so the
+ * normalization can never drift between them.
+ */
+const playgroundConfigSchema = z
+  .union([
+    z.boolean(),
+    z.strictObject({
+      enabled: z.boolean().default(true),
+      proxy: z.union([z.boolean(), z.string()]).default(false),
+    }),
+  ])
+  .default(true)
+  .transform((value) =>
+    isBoolean(value) ? { enabled: value, proxy: false } : value
+  );
+
+/**
+ * The shared shape of the API-reference blocks — only the mount route and
  * code-sample defaults differ per spec kind, so each block declares just
- * those.
+ * those (the GraphQL block derives from this via omit/extend below).
  */
 const referenceConfigSchema = (defaults: {
   codeSamples: string[];
@@ -1591,27 +1771,8 @@ const referenceConfigSchema = (defaults: {
     enabled: z.boolean().default(false),
     /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
     expandSchemas: z.boolean().default(false),
-    /**
-     * The interactive "Try it" panel on operation pages (Blume renderer). On by
-     * default; `false` hides it. The object form keeps it on and sets `proxy`,
-     * the CORS escape hatch the OpenAPI Send button routes requests through: a
-     * proxy URL, or `true` for the built-in `/_api-proxy` endpoint (which
-     * requires `deployment.output: "server"`). Booleans normalize to the object
-     * shape so consumers read `{ enabled, proxy }` directly. `proxy` is
-     * OpenAPI-only — an event composer's WebSocket connect is direct.
-     */
-    playground: z
-      .union([
-        z.boolean(),
-        z.strictObject({
-          enabled: z.boolean().default(true),
-          proxy: z.union([z.boolean(), z.string()]).default(false),
-        }),
-      ])
-      .default(true)
-      .transform((value) =>
-        isBoolean(value) ? { enabled: value, proxy: false } : value
-      ),
+    /** The "Try it" panel; see {@link playgroundConfigSchema}. */
+    playground: playgroundConfigSchema,
     /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
     renderer: z.enum(["blume", "scalar"]).default("blume"),
     /** Where the reference mounts. */
@@ -1651,6 +1812,43 @@ const asyncapiConfigSchema = referenceConfigSchema({
   route: "/events",
 });
 
+/**
+ * A single GraphQL schema rendered by the reference. `spec` is a local path or
+ * an `http(s)` URL to SDL text or an introspection JSON result; `endpoint` is
+ * the live GraphQL API URL the playground and code samples target (a schema,
+ * unlike an OpenAPI document, names no server).
+ */
+const graphqlSourceSchema = openapiSourceSchema.extend({
+  /** URL of the live GraphQL endpoint (playground + code samples). */
+  endpoint: z.string().optional(),
+});
+
+export type GraphqlSource = z.input<typeof graphqlSourceSchema>;
+
+/**
+ * GraphQL reference. Blume lowers the schema (SDL or introspection JSON) to
+ * one real page per root field — grouped as Queries/Mutations/Subscriptions —
+ * plus one page per named type (Objects, Input Objects, Enums, Interfaces,
+ * Unions, Scalars), all included in the sidebar, search, llms.txt, and OG.
+ * Always Blume-rendered: the Scalar SPA reads OpenAPI documents only, so the
+ * block declares no `renderer`/`scalar`/`theme` escape hatches.
+ */
+const graphqlConfigSchema = referenceConfigSchema({
+  codeSamples: ["curl", "js", "python"],
+  route: "/graphql",
+})
+  // No `renderer`/`scalar`/`theme` escape hatches (the Scalar SPA reads
+  // OpenAPI documents only) and no `expandSchemas` (GraphQL field tables have
+  // no nesting) — everything else, the playground normalization included, is
+  // the shared reference shape.
+  .omit({ expandSchemas: true, renderer: true, scalar: true, theme: true })
+  .extend({
+    /** Default live endpoint URL for every source (per-source `endpoint` wins). */
+    endpoint: z.string().optional(),
+    /** One or more schemas; each renders on its own route by default. */
+    sources: z.array(graphqlSourceSchema).default([]),
+  });
+
 /**
  * Opt-in custom frontmatter keys. `extend` maps each extra key a project's
  * pages may carry (e.g. `owner`, `reviewedAt`) to a validation schema; the
@@ -1736,6 +1934,7 @@ export const blumeConfigSchema = z
     /** Opt-in custom frontmatter keys, validated by user-supplied schemas. */
     frontmatter: frontmatterConfigSchema.prefault({}),
     github: githubConfigSchema.optional(),
+    graphql: graphqlConfigSchema.prefault({}),
     i18n: i18nConfigSchema.optional(),
     image: imageConfigSchema.prefault({}),
     integrations: z.array(z.custom<AstroIntegration>()).default([]),

package/src/core/server-features.ts

@@ -1,3 +1,4 @@
+import { needsPlaygroundProxy } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import type { ResolvedConfig } from "./schema.ts";
 
@@ -14,15 +15,10 @@ export const serverFeatures = (config: ResolvedConfig): string[] => {
   if (config.ai.mcp.enabled) {
     features.push("MCP server");
   }
-  // The built-in playground proxy (`openapi.playground.proxy: true`) is a
-  // live fetch endpoint at `/_api-proxy`; an external proxy URL (string) or a
-  // proxy-less playground stays fully static.
-  if (
-    config.openapi.enabled &&
-    config.openapi.renderer === "blume" &&
-    config.openapi.playground.enabled &&
-    config.openapi.playground.proxy === true
-  ) {
+  // The built-in playground proxy (`playground.proxy: true` on the OpenAPI or
+  // GraphQL block) is a live fetch endpoint at `/_api-proxy`; an external
+  // proxy URL (string) or a proxy-less playground stays fully static.
+  if (needsPlaygroundProxy(config)) {
     features.push("API playground proxy");
   }
   // Mixedbread (and any future provider) that proxies queries through a secret

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

@@ -5,6 +5,7 @@ import { gfm } from "micromark-extension-gfm";
 import stringWidth from "string-width";
 
 import matter from "../frontmatter.ts";
+import { PUBLIC_API_URL } from "../github.ts";
 import { columnsPrefix } from "../text-width.ts";
 import {
   hashText,
@@ -55,7 +56,6 @@ interface GithubRelease {
   tag_name: string;
 }
 
-const DEFAULT_BASE_URL = "https://api.github.com";
 const DEFAULT_LIMIT = 100;
 const PER_PAGE = 100;
 
@@ -203,7 +203,7 @@ export const githubReleasesSource = (
   ctx: SourceContext
 ): ContentSource => {
   const doFetch = options.fetchImpl ?? globalThis.fetch;
-  const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/u, "");
+  const base = (options.baseUrl ?? PUBLIC_API_URL).replace(/\/$/u, "");
   const max = options.limit ?? DEFAULT_LIMIT;
   const cache = snapshotCache(ctx.cacheDir);
   let snapshot = new Map<string, SourceEntry>();