blume 1.5.2 → 1.6.0

package/src/core/config-input.ts

@@ -7,6 +7,7 @@ import type { CodeTheme } from "../markdown/themes.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type {
   blumeConfigSchema,
+  GraphqlSource,
   OpenApiSource,
   OpenInChatProvider,
   SearchProvider,
@@ -232,6 +233,21 @@ export interface NotionSource {
   publishedValue?: string;
 }
 
+/**
+ * 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.
+ */
+export interface ObsidianSource {
+  type: "obsidian";
+  /** Vault folder names to skip at any depth, in addition to dot-folders. */
+  exclude?: string[];
+  /** Namespaces this source's routes under `/<prefix>/`; e.g. `vault`. */
+  prefix?: string;
+  /** Vault directory, absolute or relative to the project root. */
+  vault: string;
+}
+
 /**
  * A user-provided {@link ContentSource} instance, passed straight through. This
  * is the extension point for adapters with custom serializers or any other
@@ -250,6 +266,7 @@ export type ContentSourceInput =
   | GithubReleasesSource
   | SanitySource
   | NotionSource
+  | ObsidianSource
   | CustomSource;
 
 /**
@@ -446,12 +463,28 @@ export type SidebarConfig =
       items?: SidebarItemConfig[];
     };
 
+/** A plain header link, or the header's single call to action. */
+export interface HeaderAction {
+  /** Link target. An external href opens in a new tab. */
+  href: string;
+  /** Link label. */
+  label: string;
+}
+
 /** Header, sidebar, tabs, and switcher configuration. */
 export interface NavigationConfig {
+  /** Plain links in the header, left of the icon buttons. */
+  actions?: HeaderAction[];
+  /** The single primary call to action in the header, as a filled button. */
+  cta?: HeaderAction;
   /** Pinned links shown above the generated sidebar sections. */
   featured?: FeaturedLink[];
-  /** Show a GitHub repo link in the header (requires `github` configured). */
-  repo?: boolean;
+  /**
+   * The GitHub link in the header. `true` derives it from `github` (the
+   * default), `false` hides it, and an absolute URL points it anywhere on
+   * GitHub — an organization, say, when the docs repo itself is private.
+   */
+  repo?: boolean | string;
   /** Context switchers shown in the header (versions, languages, …). */
   selectors?: NavSelector[];
   /** Sidebar behavior and (optionally) an explicit sidebar tree. */
@@ -478,6 +511,11 @@ export interface RemoteFontInput {
   name: string;
   /** Which provider serves the family. Defaults to `google`. */
   provider?: "google" | "fontsource" | "bunny" | "fontshare";
+  /**
+   * Character subsets to load (`"latin"`, `"vietnamese"`, `"cyrillic"`, …).
+   * Defaults to `latin` plus whatever the configured locales need.
+   */
+  subsets?: string[];
   /** Weights (or variable ranges like `"100..900"`) to load. Defaults to `[400, 500, 600, 700]`. */
   weights?: (number | string)[];
 }
@@ -603,6 +641,12 @@ export interface SearchConfig {
   algolia?: AlgoliaSearch;
   /** Indexing behavior. */
   indexing?: {
+    /**
+     * Index fenced code (body and title) in the source-built search indexes —
+     * the client index, hosted syncs, and the MCP `search_docs` index.
+     * Defaults to `false`; Pagefind and Mixedbread index code regardless.
+     */
+    includeCodeBlocks?: boolean;
     /** Include pages marked `hidden` in the search index. Defaults to `false`. */
     includeHiddenPages?: boolean;
   };
@@ -701,6 +745,22 @@ export interface AskConfig {
 
 /** What the `llms.txt`/`llms-full.txt` files include. */
 export interface LlmsTxtConfig {
+  /**
+   * Markdown placed after the title and summary in `llms.txt`, before the
+   * page sections — the llms.txt spec's "details" block. Use it to tell
+   * agents when to reach for the product and how to call it (a "When to use"
+   * heading, the install command, the package name). Blank values are
+   * dropped.
+   *
+   * ```ts
+   * ai: {
+   *   llmsTxt: {
+   *     details: "## When to use Acme\n\nUse Acme when…",
+   *   },
+   * }
+   * ```
+   */
+  details?: string;
   /** Emit `llms.txt` and `llms-full.txt`. Defaults to `true`. */
   enabled?: boolean;
   /**
@@ -1108,6 +1168,68 @@ export interface OgConfig {
   titles?: Record<string, string>;
 }
 
+/** A schema.org `PostalAddress`; give whichever parts apply. */
+export interface PostalAddressConfig {
+  /** Country name or ISO 3166-1 alpha-2 code (`"US"`). */
+  addressCountry?: string;
+  /** City or locality. */
+  addressLocality?: string;
+  /** State, province, or region. */
+  addressRegion?: string;
+  postalCode?: string;
+  streetAddress?: string;
+}
+
+/**
+ * The organization behind the site, emitted in every page's JSON-LD as an
+ * `Organization` node that the WebSite and article nodes cite as publisher.
+ * Contact details become a `ContactPoint` and the address a `PostalAddress` —
+ * the fields AI agents check to verify a business before recommending it.
+ * Requires `deployment.site` (the node needs an absolute identifier).
+ */
+export interface OrganizationConfig {
+  /** Postal address, emitted as a `PostalAddress` when any part is given. */
+  address?: PostalAddressConfig;
+  /** `ContactPoint.contactType` for the email/telephone. Defaults to `"customer support"`. */
+  contactType?: string;
+  /** Public contact email. */
+  email?: string;
+  /** Logo: an absolute URL or a root-relative path (`"/logo.svg"`). */
+  logo?: string;
+  /** Organization name. Defaults to the site title. */
+  name?: string;
+  /** Profile URLs that identify the organization (GitHub, X, LinkedIn, …). */
+  sameAs?: string[];
+  /** Public contact telephone number. */
+  telephone?: string;
+  /** Organization website. Defaults to the site origin. */
+  url?: string;
+}
+
+/**
+ * The product the site documents, emitted on the homepage as a
+ * `SoftwareApplication` JSON-LD node — the identity type that tells agents
+ * what the site is about. Requires `deployment.site`.
+ */
+export interface SoftwareConfig {
+  /** schema.org application category. Defaults to `"DeveloperApplication"`. */
+  applicationCategory?: string;
+  /** Product description. Defaults to the site description. */
+  description?: string;
+  /** License URL or SPDX identifier (`"MIT"`). */
+  license?: string;
+  /** Product name. Defaults to the site title. */
+  name?: string;
+  /** Supported platform(s), e.g. `"Node.js 22+"`. */
+  operatingSystem?: string;
+  /** Price, emitted as an `Offer`; `0` marks the software free. */
+  price?: number | string;
+  /** Currency of `price` (ISO 4217). Defaults to `"USD"`. */
+  priceCurrency?: string;
+  /** Package registry, repository, and profile URLs for the product. */
+  sameAs?: string[];
+}
+
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
 export interface SeoConfig {
   /**
@@ -1119,12 +1241,39 @@ export interface SeoConfig {
   contentSignals?: ContentSignalsConfig;
   /** Per-page Open Graph image generation. */
   og?: OgConfig;
+  /**
+   * The organization behind the site, added to every page's JSON-LD as an
+   * `Organization` node with contact point and address.
+   *
+   * ```ts
+   * seo: {
+   *   organization: {
+   *     email: "hello@acme.com",
+   *     logo: "/logo.svg",
+   *     sameAs: ["https://github.com/acme", "https://x.com/acme"],
+   *   },
+   * }
+   * ```
+   */
+  organization?: OrganizationConfig;
   /** Generate robots.txt (with a Sitemap reference when available). Defaults to `true`. */
   robots?: boolean;
   /** RSS/Atom feeds. */
   rss?: RssConfig;
   /** Generate sitemap.xml (requires `deployment.site`). Defaults to `true`. */
   sitemap?: boolean;
+  /**
+   * The documented product, added to the homepage's JSON-LD as a
+   * `SoftwareApplication` node. `true` takes every default (name and
+   * description from the site); the object form fills in the rest.
+   *
+   * ```ts
+   * seo: {
+   *   software: { license: "MIT", operatingSystem: "Node.js 22+", price: 0 },
+   * }
+   * ```
+   */
+  software?: boolean | SoftwareConfig;
   /** Emit schema.org JSON-LD in each page's `<head>`. Defaults to `true`. */
   structuredData?: boolean;
   /**
@@ -1146,10 +1295,27 @@ export interface SeoConfig {
 
 /** Source repository, powering "Edit this page" links and the header repo link. */
 export interface GithubConfig {
+  /**
+   * REST API base, for a `<GithubInfo>` card against an Enterprise instance.
+   * Derived from `host` when unset: `api.github.com` for github.com, an `api.`
+   * subdomain for an Enterprise Cloud data-residency tenant, and `/api/v3` for
+   * Enterprise Server. Must be an HTTP(S) URL, and is reduced to an origin plus
+   * its path — the repository route is appended to it.
+   */
+  api?: string;
   /** Default branch. Defaults to `main`. */
   branch?: string;
   /** Path from the repo root to the project root (for monorepos). */
   dir?: string;
+  /**
+   * Origin of the GitHub instance the repo lives on. Defaults to
+   * `https://github.com`; set it to an Enterprise host (for example
+   * `https://github.acme.com` or `https://acme.ghe.com`) so the header link,
+   * edit links, and the agent manifest point at that instance. Must be an
+   * HTTP(S) URL, and is reduced to its origin — every repo URL is built by
+   * appending to it.
+   */
+  host?: string;
   /** Repository owner (user or org). */
   owner: string;
   /** Repository name. */
@@ -1278,6 +1444,45 @@ export interface AsyncApiConfig extends ReferenceConfig {
   route?: string;
 }
 
+/**
+ * GraphQL reference. Blume lowers the schema — SDL text or an introspection
+ * JSON result, local or remote — into 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 in the sidebar,
+ * search, llms.txt, and OG. Always Blume-rendered — the embedded Scalar SPA
+ * reads OpenAPI documents only — so unlike the other reference blocks there
+ * is no `renderer` opt-out.
+ */
+export interface GraphqlConfig {
+  /**
+   * Code-sample languages shown per operation. Defaults to
+   * `["curl", "js", "python"]`.
+   */
+  codeSamples?: string[];
+  /** Turn the reference on. Defaults to `false`. */
+  enabled?: boolean;
+  /**
+   * URL of the live GraphQL endpoint the playground and code samples target —
+   * a schema, unlike an OpenAPI document, names no server. Applies to every
+   * source in the block; a per-source `endpoint` wins.
+   */
+  endpoint?: string;
+  /**
+   * The interactive "Try it" panel on operation pages. 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"`).
+   */
+  playground?: boolean | { enabled?: boolean; proxy?: boolean | string };
+  /** Where the reference mounts. Defaults to `/graphql`. */
+  route?: string;
+  /** One or more schemas; each renders on its own route by default. */
+  sources?: GraphqlSource[];
+  /** Shorthand for a single source: `sources: [{ spec }]`. */
+  spec?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Misc top-level unions
 // ---------------------------------------------------------------------------
@@ -1456,6 +1661,8 @@ export interface BlumeConfig {
   frontmatter?: FrontmatterConfig;
   /** Source repository (Edit-this-page links and the header repo link). */
   github?: GithubConfig;
+  /** Native GraphQL reference (root fields and named types as real pages). */
+  graphql?: GraphqlConfig;
   /** Internationalization (opt-in multi-locale). */
   i18n?: I18nConfig;
   /** Image optimization: remote-host authorization for the image service. */

package/src/core/config.ts

@@ -50,11 +50,13 @@ import type { Diagnostic } from "./types.ts";
  *   custom `ContentSource`). Omit `sources` and the top-level `root` becomes one
  *   implicit filesystem source.
  * - `navigation` — sidebar, header `tabs`, `selectors` (version/language/product
- *   switchers), pinned `featured` links, and the `repo` link toggle. Omit
- *   `sidebar` to generate it from the content tree.
+ *   switchers), pinned `featured` links, header `actions` and the one `cta`,
+ *   and the `repo` link (a toggle, or a URL). Omit `sidebar` to generate it
+ *   from the content tree.
  * - `redirects` — `{ from, to, status }` rules (301 by default).
- * - `github` — `{ owner, repo, branch, dir }`, powering "Edit this page" links
- *   and the header repo link.
+ * - `github` — `{ owner, repo, branch, dir, host, api }`, powering "Edit this
+ *   page" links and the header repo link; `host` points them at a GitHub
+ *   Enterprise instance, `api` overrides the REST base derived from it.
  *
  * **Appearance**
  * - `theme` — `accent` color, `fonts` (curated slugs, any provider family, or

package/src/core/content-assets.ts

@@ -19,6 +19,9 @@ import {
   nextFenceState,
   targetOffsetIn,
 } from "./sources/normalize.ts";
+import { readExpandedEntryText } from "./sources/read.ts";
+import type { ContentSource } from "./sources/types.ts";
+import type { PageRecord } from "./types.ts";
 
 /**
  * Colocated content images — `![alt](./diagram.png)` next to the page that
@@ -217,22 +220,30 @@ export const rewriteRelativeImages = (options: {
  * Every colocated image the project's pages reference, keyed by endpoint param.
  * Serialized to `generated/content-assets.json`, which the
  * `/blume-assets/[...asset]` endpoint reads to serve the original files. Runs
- * the same rewrite the agent-Markdown builders apply, so the served set and the
- * rewritten URLs can't drift apart.
+ * the same rewrite the agent-Markdown builders apply — over the same
+ * include-expanded text, so a partial's colocated images (rebased into the
+ * including page by the expander) are served too — keeping the served set and
+ * the rewritten URLs from drifting apart.
  */
 export const collectContentAssets = async (project: {
   context: { root: string };
-  manifest: { routes: { sourcePath?: string }[] };
+  manifest: { routes: { id: string; sourcePath?: string }[] };
+  graph: { pages: PageRecord[] };
+  sources?: ContentSource[];
 }): Promise<Record<string, string>> => {
+  const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
   const files: Record<string, string> = {};
   await Promise.all(
     project.manifest.routes.map(async (route) => {
       if (!route.sourcePath) {
         return;
       }
+      const page = pageById.get(route.id);
       let source: string;
       try {
-        source = await readFile(route.sourcePath, "utf-8");
+        source = page
+          ? await readExpandedEntryText(project, page)
+          : await readFile(route.sourcePath, "utf-8");
       } catch {
         return;
       }

package/src/core/data.ts

@@ -1,3 +1,4 @@
+import type { StructuredDataIdentity } from "../seo/jsonld.ts";
 import type { FontHead } from "../theme/fonts.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
@@ -128,12 +129,27 @@ export interface BlumeDataConfig {
    * Which agent-discovery resources exist for the layout to advertise in every
    * page's `<head>` (`seo.agentReadability`, `ai.llmsTxt.enabled`) — the HTML
    * counterpart of the homepage-only HTTP `Link` header, for agents that enter
-   * on a deep page (see `ai/link-headers.ts`).
+   * on a deep page (see `ai/link-headers.ts`). `sitemap` (`seo.sitemap` with a
+   * `deployment.site`, the condition under which one is emitted) feeds the
+   * 404 page's recovery links rather than the head.
    */
-  discovery: { agentReadability: boolean; llmsTxt: boolean };
+  discovery: { agentReadability: boolean; llmsTxt: boolean; sitemap: boolean };
   favicon: BlumeFavicon;
   feedback: boolean;
+  /**
+   * Repo coordinates for content components that address the API or build
+   * their own repo links (`<GithubInfo>`, the OG card's footer slug), carrying
+   * `host`/`api` so an Enterprise instance is reachable; `null` when `github`
+   * is unset. The plain repository URL stays on `repoUrl`.
+   */
+  github: { api: string; host: string; owner: string; repo: string } | null;
   i18n: BlumeDataI18n | null;
+  /**
+   * Site identity for JSON-LD (`seo.organization`, `seo.software`), read by
+   * the layouts straight from the snapshot so custom pages get it without
+   * threading a prop; `null` when neither is configured.
+   */
+  identity: StructuredDataIdentity | null;
   /** `markdown.imageZoom`: click-to-zoom content images. */
   imageZoom: boolean;
   logo: BlumeLogo | null;

package/src/core/diagnostics.ts

@@ -25,6 +25,7 @@ const DOCS_DEPLOYMENT = "/docs/deployment";
 const DOCS_REFERENCE_CLI = "/docs/reference/cli";
 const DOCS_CONTENT_SOURCES = "/docs/content/sources";
 const DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
+const DOCS_CONTENT_INCLUDES = "/docs/content/includes";
 
 /** Diagnostic code → the docs page that explains it. */
 const DOCS_PATHS = new Map(
@@ -42,6 +43,11 @@ const DOCS_PATHS = new Map(
     BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
     BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
     BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
+    BLUME_INCLUDE_CYCLE: DOCS_CONTENT_INCLUDES,
+    BLUME_INCLUDE_NOT_FOUND: DOCS_CONTENT_INCLUDES,
+    BLUME_INCLUDE_OUTSIDE_ROOT: DOCS_CONTENT_INCLUDES,
+    BLUME_MDX_CURLY_ANCHOR: "/docs/content/syntax",
+
     BLUME_META_INVALID: "/docs/content/meta",
     BLUME_META_LOAD_FAILED: "/docs/content/meta",
     BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
@@ -59,6 +65,8 @@ const DOCS_PATHS = new Map(
     BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
     BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
     BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
+    BLUME_WIKILINK_AMBIGUOUS: DOCS_CONTENT_SOURCES,
+    BLUME_WIKILINK_UNRESOLVED: DOCS_CONTENT_SOURCES,
   })
 );
 

package/src/core/frontmatter.ts

@@ -1,13 +1,15 @@
 import baseMatter from "gray-matter";
 import { dump, load } from "js-yaml";
 
+import { YAML_SCHEMA } from "./yaml.ts";
+
 // gray-matter@4 binds js-yaml 3's `safeLoad`/`safeDump` as its default YAML
-// engine. In a workspace that pins js-yaml to v4 — where those functions were
-// removed — parsing front matter throws "Function yaml.safeLoad is removed in
-// js-yaml 4." Every Blume front-matter call routes through this `matter`
-// wrapper, which supplies an explicit engine built on `load`/`dump`. Both exist
-// in js-yaml 3 and 4, so Blume is immune to whichever version the consumer's
-// install resolves for gray-matter.
+// engine. In a workspace that resolves a newer js-yaml for gray-matter — v4
+// replaced those functions with throwing stubs, v5 dropped them — parsing
+// front matter throws "Function yaml.safeLoad is removed in js-yaml 4." Every
+// Blume front-matter call routes through this `matter` wrapper, which supplies
+// an explicit engine built on Blume's own `load`/`dump`, so Blume is immune to
+// whichever version the consumer's install resolves for gray-matter.
 
 type MatterInput = Parameters<typeof baseMatter>[0];
 type MatterOptions = Parameters<typeof baseMatter>[1];
@@ -22,7 +24,8 @@ const yamlEngine = {
   // block is a YAML mapping, and js-yaml returns a scalar only for degenerate
   // input, which gray-matter treats the same way its bundled engine's output
   // is treated.
-  parse: (input: string): object => (load(input) ?? {}) as object,
+  parse: (input: string): object =>
+    (load(input, { schema: YAML_SCHEMA }) ?? {}) as object,
   stringify: (data: FrontMatterData): string => dump(data),
 };
 
@@ -109,11 +112,20 @@ const matter = Object.assign(
   {
     read: (filepath: ReadArgs[0], options?: ReadArgs[1]) =>
       baseMatter.read(filepath, withYamlEngine(options)),
+    // A string is the body to emit, not a document to parse: gray-matter
+    // would otherwise run `matter()` over it, and a body that opens with a
+    // `---` divider reads as a second front matter block — js-yaml either
+    // throws or swallows the opening paragraph into the YAML header.
     stringify: (
       file: StringifyArgs[0],
       data: StringifyArgs[1],
       options?: StringifyArgs[2]
-    ): string => baseMatter.stringify(file, data, withYamlEngine(options)),
+    ): string =>
+      baseMatter.stringify(
+        isStringInput(file) ? { content: file } : file,
+        data,
+        withYamlEngine(options)
+      ),
   }
 );
 

package/src/core/github.ts

@@ -0,0 +1,71 @@
+/**
+ * Repository URL derivation for `config.github`.
+ *
+ * Every repo-derived link — the header mark, per-page edit links, the agent
+ * manifest's `repository` — is built from `host`, which defaults to github.com
+ * but accepts a GitHub Enterprise origin so self-hosted and data-resident
+ * installations get working links instead of ones pointing at the public site.
+ *
+ * The REST base is derived from the host unless `api` is set explicitly, since
+ * the two Enterprise flavors expose it differently: Enterprise Cloud with data
+ * residency serves it from an `api.` subdomain of the same host, Enterprise
+ * Server from `/api/v3` on the host itself.
+ *
+ * `host` arrives as a bare origin and `api` as an origin plus path, both with
+ * no trailing slash — the config schema normalizes them — so nothing here
+ * re-trims user input.
+ */
+
+import type { ResolvedConfig } from "./schema.ts";
+
+/** The resolved `github` block, which the config leaves optional. */
+export type GithubTarget = NonNullable<ResolvedConfig["github"]>;
+
+/** The public instance every `host` defaults to. */
+export const PUBLIC_HOST_URL = "https://github.com";
+/** The public instance's REST base. */
+export const PUBLIC_API_URL = "https://api.github.com";
+const PUBLIC_HOSTNAME = "github.com";
+/** Enterprise Cloud with data residency: `<tenant>.ghe.com`. */
+const DATA_RESIDENCY_SUFFIX = ".ghe.com";
+
+/** `owner/repo` — the bare slug, with no origin attached. */
+const repoSlug = (github: Pick<GithubTarget, "owner" | "repo">): string =>
+  `${github.owner}/${github.repo}`;
+
+/** The repository's web URL, e.g. `https://github.com/acme/docs`. */
+export const repoUrl = (
+  github: Pick<GithubTarget, "host" | "owner" | "repo">
+): string => `${github.host}/${repoSlug(github)}`;
+
+/** The base every edit link extends with a repo-relative path. */
+export const editBaseUrl = (
+  github: Pick<GithubTarget, "branch" | "host" | "owner" | "repo">
+): string => `${repoUrl(github)}/edit/${github.branch}`;
+
+/**
+ * The REST API base for `host`. An explicit `api` always wins; otherwise
+ * github.com (and any subdomain of it, `www.` say) maps to api.github.com, a
+ * data-residency tenant to its `api.` subdomain, and anything else is treated
+ * as Enterprise Server (`/api/v3`).
+ */
+export const apiUrl = (github: Pick<GithubTarget, "api" | "host">): string => {
+  if (github.api) {
+    return github.api;
+  }
+  const url = new URL(github.host);
+  const { hostname } = url;
+  if (
+    hostname === PUBLIC_HOSTNAME ||
+    hostname.endsWith(`.${PUBLIC_HOSTNAME}`)
+  ) {
+    return PUBLIC_API_URL;
+  }
+  if (hostname.endsWith(DATA_RESIDENCY_SUFFIX)) {
+    // Rebuilt through the URL so a non-default port survives alongside the
+    // subdomain rather than being dropped from the API base alone.
+    url.hostname = `api.${hostname}`;
+    return url.origin;
+  }
+  return `${github.host}/api/v3`;
+};

package/src/core/graph.ts

@@ -142,8 +142,13 @@ const buildLocaleNavigation = (
   // header tab points to its in-locale route (e.g. `/docs` -> `/fr/docs`);
   // external paths pass through. Selectors are left alone: a language
   // selector's items intentionally target specific locales.
+  // `//host/path` is protocol-relative — an external URL that happens to start
+  // with a slash, so it must not pick up a locale prefix. `withBasePath` draws
+  // the same line for the same reason.
   const localizePath = (path: string): string =>
-    path.startsWith("/") ? localizeRoute(path, code, i18n) : path;
+    path.startsWith("/") && !path.startsWith("//")
+      ? localizeRoute(path, code, i18n)
+      : path;
   const tabs = resolveTabLabels(
     options.navigation.tabs,
     code,
@@ -178,17 +183,22 @@ const buildLocaleNavigation = (
   // version dir is hoisted in front (`v1.0/fr`), matching `discoverFolderMeta`.
   const localeDir =
     i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "";
+  // Internal featured and header hrefs are localized like tab paths — a pinned
+  // `/changelog` link rendered on `/fr/…` pages must stay inside the reader's
+  // locale, not kick them back to the default one.
+  const localizeHref = <T extends { href: string }>(item: T): T => ({
+    ...item,
+    href: localizePath(item.href),
+  });
+  const { actions, cta, featured } = options.navigation;
+
   return buildNavigation(localePages, {
+    actions: actions?.map(localizeHref),
     basePath: options.basePath ?? "",
+    cta: cta ? localizeHref(cta) : null,
     diagnostics,
     display: options.navigation.sidebar.display,
-    // Internal featured hrefs are localized like tab paths — a pinned
-    // `/changelog` link rendered on `/fr/…` pages must stay inside the
-    // reader's locale, not kick them back to the default one.
-    featured: options.navigation.featured?.map((link) => ({
-      ...link,
-      href: localizePath(link.href),
-    })),
+    featured: featured?.map(localizeHref),
     folderMeta: options.folderMeta,
     // The localized tree root ("/" for the hidden default, "/fr" otherwise;
     // "/fr/v1.0" inside a snapshot): the tab pointing here spans the whole
@@ -283,7 +293,9 @@ const buildVersionNavigation = (
   }
   return {
     "": buildNavigation(versionPages, {
+      actions: options.navigation.actions,
       basePath: options.basePath ?? "",
+      cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
       featured: options.navigation.featured,
@@ -328,7 +340,9 @@ export const buildContentGraph = (
     ));
   } else {
     navigation = buildNavigation(currentPages, {
+      actions: options.navigation.actions,
       basePath: options.basePath ?? "",
+      cta: options.navigation.cta,
       diagnostics,
       display: options.navigation.sidebar.display,
       featured: options.navigation.featured,