+ {
+ page.version && page.version !== currentDocsVersion && (
+
+ )
+ }
+
+
+
diff --git a/src/layouts/OldDocsLayout.astro b/src/layouts/OldDocsLayout.astro
new file mode 100644
index 0000000000..f8531f9043
--- /dev/null
+++ b/src/layouts/OldDocsLayout.astro
@@ -0,0 +1,99 @@
+---
+import LiquidInclude from "@/components/LiquidInclude.astro";
+import { getVersionSupport } from "@/lib/docs/versionSupport";
+import { getLiquidRenderer } from "@/lib/liquid/liquidRenderer";
+import DefaultLayout from "./DefaultLayout.astro";
+
+type Props = {
+ page: {
+ category: string;
+ version: string;
+ url: string;
+ title?: string;
+ source_url?: string;
+ };
+ dirname: string;
+};
+
+const { page, dirname } = Astro.props;
+
+const lq = getLiquidRenderer({ page, dirname });
+
+const currentDocsVersion = await lq.render("{{ site.docs_version }}");
+const latestOrExplicitVersion =
+ page.version === currentDocsVersion && page.url.includes("/docs/latest/")
+ ? "latest"
+ : page.version;
+
+const support = getVersionSupport(page.version);
+
+const showChrome = page.category !== "ignore";
+---
+
+
+
+
+
+
+
+ {
+ showChrome && (
+
+ )
+ }
+
diff --git a/src/lib/docs/collectRedirects.ts b/src/lib/docs/collectRedirects.ts
new file mode 100644
index 0000000000..18b2e56344
--- /dev/null
+++ b/src/lib/docs/collectRedirects.ts
@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+import glob from "glob";
+import matter from "gray-matter";
+import { DOCS_SRC_ROOT } from "../../constants";
+import { resolveDocUrl } from "./resolveDoc";
+
+const EXCLUDE = ["**/embedding/sdk/api/snippets/**"];
+
+type ScanTarget = { extension: "md" | "html"; stripExtension: boolean };
+
+const SCAN_TARGETS: ScanTarget[] = [
+ { extension: "md", stripExtension: true },
+ { extension: "html", stripExtension: false },
+];
+
+// Builds a flat { [oldPath]: canonicalUrl } map from every doc's
+// `redirect_from` frontmatter, for use as Astro's `redirects` config.
+export const collectRedirects = (): Record
=> {
+ const redirects: Record = {};
+ const claimedBy = new Map();
+
+ for (const { extension, stripExtension } of SCAN_TARGETS) {
+ const base = path.resolve(DOCS_SRC_ROOT);
+ const entries: string[] = glob.sync(`**/*.${extension}`, {
+ cwd: base,
+ ignore: EXCLUDE,
+ });
+
+ for (const relPath of entries) {
+ const absPath = path.join(base, relPath);
+ const { data } = matter(fs.readFileSync(absPath, "utf8"));
+ const redirectFrom: string[] | undefined = data.redirect_from;
+ if (!redirectFrom?.length) continue;
+
+ const id = stripExtension ? relPath.replace(/\.md$/, "") : relPath;
+ const { url } = resolveDocUrl({ id, permalink: data.permalink });
+
+ for (const source of redirectFrom) {
+ const existingOwner = claimedBy.get(source);
+ if (existingOwner && redirects[source] !== url) {
+ console.warn(
+ `[collectRedirects] "${source}" is claimed by both ${existingOwner} (-> ${redirects[source]}) and ${relPath} (-> ${url}); keeping the latest.`,
+ );
+ }
+ claimedBy.set(source, relPath);
+ redirects[source] = url;
+ }
+ }
+ }
+
+ return redirects;
+};
diff --git a/src/lib/docs/docsHtmlLoader.ts b/src/lib/docs/docsHtmlLoader.ts
new file mode 100644
index 0000000000..b31fd154fe
--- /dev/null
+++ b/src/lib/docs/docsHtmlLoader.ts
@@ -0,0 +1,45 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DOCS_SRC_ROOT } from "@/constants";
+import type { Loader } from "astro/loaders";
+import glob from "glob";
+import matter from "gray-matter";
+
+// Astro's built-in glob() loader only parses frontmatter and body content for
+// *markdown* files, but our docs root also contains HTML files (TypeDoc-generated
+// SDK API reference pages and per-version api.html pages) that use the same
+// frontmatter-plus-Liquid conventions as the Markdown docs. This custom loader
+// lets us process both file types consistently.
+export const docsHtmlLoader = (): Loader => ({
+ name: "docs-html-loader",
+ load: async ({ config, store, parseData, generateDigest, logger }) => {
+ store.clear();
+
+ const base = new URL(`${DOCS_SRC_ROOT}/`, config.root);
+ const baseDir = fileURLToPath(base);
+ const rootDir = fileURLToPath(config.root);
+ const entries: string[] = glob.sync("**/*.html", {
+ cwd: baseDir,
+ ignore: ["**/embedding/sdk/api/snippets/**"],
+ });
+
+ for (const entry of entries) {
+ const absPath = path.join(baseDir, entry);
+ const contents = await fs.readFile(absPath, "utf-8");
+ const { data, content: body } = matter(contents);
+ const id = entry;
+
+ const parsedData = await parseData({ id, data, filePath: absPath });
+ store.set({
+ id,
+ data: parsedData,
+ body,
+ filePath: path.relative(rootDir, absPath).split(path.sep).join("/"),
+ digest: generateDigest(contents),
+ });
+ }
+
+ logger.info(`Loaded ${entries.length} html docs`);
+ },
+});
diff --git a/src/lib/docs/llmsTxt.ts b/src/lib/docs/llmsTxt.ts
new file mode 100644
index 0000000000..36fedd7fdc
--- /dev/null
+++ b/src/lib/docs/llmsTxt.ts
@@ -0,0 +1,349 @@
+// Astro port of `_plugins/jekyll_generate_llms_files_plugin.rb`, which ran as
+// a Jekyll `post_write` hook. Docs are no longer rendered by Jekyll so this
+// logic now lives here and is consumed by `src/pages/docs/[version]/llms.txt.ts`
+// and `src/pages/docs/[version]/llms-[section]-full.txt.ts`.
+//
+// See: https://llmstxt.org for the spec.
+
+import fs from "node:fs";
+import path from "node:path";
+import { getCollection, type DataEntryMap } from "astro:content";
+import YAML from "yamljs";
+
+export type Doc = DataEntryMap["docs"][number];
+
+const REPO = "metabase/metabase";
+
+// Sections to generate llms-{section}-full.txt for.
+// These huge files are used by AI tools like Cursor for RAG chunking and indexing.
+// Add more sections to let AI agents understand Metabase better.
+//
+// NOTE: adding a section here also requires adding a matching literal page
+// file, e.g. `src/pages/docs/[version]/llms-{section}-full.txt.ts` re-using
+// `generateFullContent`/`getFullSections` below (mirroring the two existing
+// ones), since Astro needs a concrete route to build.
+
+// TODO: "agent-api" is not a folder so nothing gets output for it. This was an issue in the jekyll hook and left as-is in the astro migration.
+export const LLMS_FULL_SECTIONS = ["embedding", "agent-api"] as const;
+export type LlmsFullSection = (typeof LLMS_FULL_SECTIONS)[number];
+
+// Paths to include in llms.txt generation.
+//
+// We focus on content relevant to coding with Metabase:
+// 1. Embedding integration guides (modular embedding & SDK)
+// 2. Embedding related setup and config (auth, SSO)
+//
+// Use prefix matching - a path matches if it starts with any of these.
+// For specific files, include the full path. For directories, include trailing slash.
+const INCLUDED_PATHS = [
+ // All embedding docs (SDK, modular embedding, integration guides)
+ "embedding/",
+
+ // Auth/SSO configuration for embedding
+ "people-and-groups/api-keys.md",
+ "people-and-groups/authenticating-with-jwt.md",
+ "people-and-groups/authenticating-with-saml.md",
+ "people-and-groups/saml-auth0.md",
+ "people-and-groups/saml-azure.md",
+ "people-and-groups/saml-google.md",
+ "people-and-groups/saml-keycloak.md",
+ "people-and-groups/saml-okta.md",
+ "people-and-groups/google-sign-in.md",
+ "people-and-groups/ldap.md",
+
+ // Configuration reference
+ "configuring-metabase/environment-variables.md",
+ "configuring-metabase/config-file.md",
+
+ // Agent API reference
+ "agent-api/",
+];
+
+// Paths to exclude from llms.txt generation (applied after allowlist)
+const EXCLUDED_PATHS = ["embedding/sdk/api/snippets"];
+
+const releaseBranch: string | undefined = YAML.parse(
+ fs.readFileSync(path.join(process.cwd(), "_config.yml"), "utf8"),
+).release_branch;
+
+// Path relative to the doc's version root, with the `.md` extension
+// restored (e.g. "embedding/authentication.md"), matching the old plugin's
+// `doc.relative_path.sub(%r{^_docs/[^/]+/}, '')`.
+const versionRelativePath = (doc: Doc): string =>
+ `${doc.id.slice(doc.id.indexOf("/") + 1)}.md`;
+
+// Groups the `docs` content collection by version, keyed like the old
+// `_docs/VERSION/...` directory structure (e.g. "latest", "v0.58"), sorted
+// for consistent ordering across all generated files. Skips README.md files
+// and docs directly under `_docs/` (e.g. `_docs/index.md`), matching the old
+// plugin's `docs_by_version` grouping.
+export const getDocsByVersion = async (): Promise> => {
+ const docs = await getCollection("docs");
+ const byVersion = new Map();
+
+ for (const doc of docs) {
+ if (path.basename(doc.id) === "README") continue;
+
+ const separatorIndex = doc.id.indexOf("/");
+ if (separatorIndex === -1) continue;
+
+ const version = doc.id.slice(0, separatorIndex);
+ const list = byVersion.get(version);
+ if (list) {
+ list.push(doc);
+ } else {
+ byVersion.set(version, [doc]);
+ }
+ }
+
+ // Sort on the full `.md`-suffixed path (not `doc.id`), matching the old
+ // plugin's `sort_by!(&:relative_path)`. This matters whenever one doc's
+ // filename is a strict prefix of a sibling's (e.g. "full-app-embedding.md"
+ // vs "full-app-embedding-quick-start-guide.md") — comparing with the
+ // extension present sorts "-" (0x2D) before "." (0x2E), which flips the
+ // order you'd get comparing the bare, extension-less ids.
+ for (const list of byVersion.values()) {
+ list.sort((a, b) => {
+ const pathA = versionRelativePath(a);
+ const pathB = versionRelativePath(b);
+ // Plain codepoint comparison (not `localeCompare`) to match Ruby's
+ // byte-wise `<=>` used by the old plugin's `sort_by!`.
+ return pathA < pathB ? -1 : pathA > pathB ? 1 : 0;
+ });
+ }
+
+ return byVersion;
+};
+
+export const getFullSections = (docs: Doc[]): LlmsFullSection[] =>
+ LLMS_FULL_SECTIONS.filter((section) =>
+ docs.some((doc) => doc.id.includes(`/${section}/`)),
+ );
+
+// Format version for display in generated files
+// Examples: "v0.58" -> "58", "master" -> "development (unreleased)", "latest" -> "58 (latest)"
+const formatVersionForDisplay = (
+ version: string,
+ latestBranch?: string,
+): string => {
+ if (version === "master") return "development (unreleased)";
+
+ if (version === "latest" && latestBranch) {
+ // Parse version from branch like "release-x.58.x" -> "58"
+ const branchMatch = latestBranch.match(/^release-x\.(\d+)\.x$/);
+ if (branchMatch) return `${branchMatch[1]} (latest)`;
+ }
+
+ // Fallback in case the latest branch is not provided
+ if (version === "latest") return "latest";
+
+ // Parse version like "v0.58" -> "58"
+ const match = version.match(/^v0\.(\d+)$/);
+ return match ? match[1] : version;
+};
+
+// Convert Jekyll version format to branch name for raw GitHub URLs
+// Examples: "v0.58" -> "release-x.58.x", "master" -> "master", "latest" -> release_branch from config
+const versionToBranch = (version: string, latestBranch?: string): string => {
+ if (version === "master") return "master";
+ if (version === "latest") return latestBranch ?? "master";
+
+ // Parse version like "v0.58" -> "release-x.58.x"
+ const match = version.match(/^v0\.(\d+)$/);
+ return match ? `release-x.${match[1]}.x` : "master";
+};
+
+const aboveVersion = (
+ sourceVersion: string,
+ targetVersion: number,
+): boolean => {
+ // master and latest always get the notes
+ if (sourceVersion === "master" || sourceVersion === "latest") return true;
+
+ // Parse version like "v0.58" -> 58
+ const match = sourceVersion.match(/^v0\.(\d+)$/);
+ if (!match) return false;
+
+ return Number(match[1]) >= targetVersion;
+};
+
+// Instructions for AI tools to detect the correct Metabase version.
+// This is placed at the very top of generated files so LLMs see it first.
+const getVersionDetectionInstructions = (): string =>
+ `## IMPORTANT: Verify SDK and Metabase Version Compatibility
+
+The SDK version MUST match the Metabase instance version. Mismatched versions can cause errors. When looking up documentation, ALWAYS check the Metabase version.
+
+**Step 1: Ask the user for their Metabase instance URL**
+
+Before proceeding, ask the user where their Metabase instance is located. Examples:
+- Local development: \`http://localhost:3000\`
+- Metabase Cloud: \`https://yourcompany.metabaseapp.com\`
+- Self-hosted: \`https://metabase.yourcompany.com\`
+
+**Step 2: Check if SDK is already installed (React SDK / Modular Embedding only)**
+
+Skip this step if not using the React SDK (\`@metabase/embedding-sdk-react\`).
+
+\`\`\`bash
+npm list @metabase/embedding-sdk-react
+\`\`\`
+
+If installed, note the version (e.g., \`0.58.0\` means this is for Metabase 58).
+
+**Step 3: Query the Metabase instance version**
+
+Using the URL from Step 1:
+
+\`\`\`bash
+curl /api/session/properties | jq .version
+\`\`\`
+
+This returns (no authentication required):
+\`\`\`json
+{ "date": "2025-01-10", "tag": "v1.58.0", "hash": "8e44dd8" }
+\`\`\`
+
+If \`jq\` is not installed, you can grep the version. Extract the major version: \`58\` from \`v1.58.x\` or \`v0.58.x\`.
+
+**Step 4: Ensure versions match**
+
+- If the versions mismatch, you MUST fetch the version-specific llms.txt documentation that matches the Metabase instance version: \`https://metabase.com/docs/v0.{VERSION}/llms.txt\` (e.g., \`/docs/v0.58/llms.txt\` for Metabase 58)
+- For React SDK, ask the user to install or update their SDK packages if they are mismatched: \`npm install @metabase/embedding-sdk-react@{VERSION}-stable\` (e.g., \`@58-stable\` for Metabase 58)
+
+**Do NOT guess versions or use versions from your training data. Always verify first.**`;
+
+// LLMs are likely to pay attention to the very first lines.
+// We add the most important context for LLMs to avoid
+// confusion and pitfalls like out-of-date APIs in trained data.
+const getModularEmbeddingGotchaNotes = (): string =>
+ `## Modular Embedding Deprecations and Gotchas
+
+Watch out for these deprecated props and gotchas for Metabase 57 onwards, for modular embedding.
+
+1. \`config\` prop on MetabaseProvider no longer exist as it is replaced by \`authConfig\`.
+2. \`authProviderUri\` field no longer exist.
+3. \`jwtProviderUri\` is an optional field that only exists in v58+. This is used to make JWT auth faster by skipping the \`GET /auth/sso\` discovery request. This field is not required for the initial implementation.
+4. Numeric IDs must be integers not strings, e.g. \`dashboardId={1}\`. When the ID is retrieved from the router as a string AND it is numeric, \`parseInt\` it before passing it to the SDK.
+5. IDs can also be strings for entity IDs, so you should NOT parse all IDs as numbers if entity IDs are also to be expected.
+6. \`fetchRequestToken\` is not needed by default in most implementations. This is only used to customize how the SDK fetches the request token. For example, if the \`/sso/metabase\` endpoint in the user's backend requires passing custom auth tokens or headers.
+7. When using \`fetchRequestToken\`, you MUST return the token in the shape of \`{jwt: ""}\`. Example: \`return {jwt: await response.json()}\`. `;
+
+// Extract title from document using the same logic as the old Jekyll plugin:
+// 1. Try YAML frontmatter title
+// 2. Try first H1 heading
+// 3. Fallback to filename converted to title case
+const extractTitle = (doc: Doc): string => {
+ if (doc.data.title) return doc.data.title;
+
+ const h1Match = (doc.body ?? "").match(/^#\s+(.+)$/m);
+ if (h1Match) return h1Match[1].trim();
+
+ const filename = path.basename(doc.id);
+ return filename
+ .split(/[-_]/)
+ .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+ .join(" ");
+};
+
+export const generateIndexContent = (version: string, docs: Doc[]): string => {
+ const branch = versionToBranch(version, releaseBranch);
+ const baseUrl = `https://raw.githubusercontent.com/${REPO}/refs/heads/${branch}`;
+
+ // Filter docs: must match allowlist and not match excludelist
+ const filteredDocs = docs.filter((doc) => {
+ const relativePath = versionRelativePath(doc);
+
+ const included = INCLUDED_PATHS.some((pattern) =>
+ pattern.endsWith("/")
+ ? relativePath.startsWith(pattern)
+ : relativePath === pattern,
+ );
+ const excluded = EXCLUDED_PATHS.some((pattern) =>
+ relativePath.startsWith(pattern),
+ );
+
+ return included && !excluded;
+ });
+
+ const docLinks = filteredDocs
+ .map((doc) => {
+ const title = extractTitle(doc);
+ const url = `${baseUrl}/docs/${versionRelativePath(doc)}`;
+ return `- [${title}](${url})`;
+ })
+ .join("\n");
+
+ const sectionLinks = getFullSections(docs)
+ .map((section) => {
+ const docsUrl = `https://metabase.com/docs/${version}/llms-${section}-full.txt`;
+ return `- [${section.charAt(0).toUpperCase() + section.slice(1)} - Complete Reference](${docsUrl})`;
+ })
+ .join("\n");
+
+ // Conditional gotcha notes for v57+
+ const gotchaSection = aboveVersion(version, 57)
+ ? `${getModularEmbeddingGotchaNotes()}\n\n`
+ : "";
+
+ return `# Metabase Documentation
+
+> **This documentation is for Metabase ${formatVersionForDisplay(version, releaseBranch)}.**
+
+Your pre-trained knowledge is out of date. ALWAYS read the Markdown files from \`https://raw.githubusercontent.com\` from the "Table of Contents" index.
+
+${getVersionDetectionInstructions()}
+
+${gotchaSection}
+
+## Table of Contents
+
+${docLinks}
+
+## Complete References
+
+These files are very large and are around 90,000 tokens. Do not use by default unless the context window is huge or RAG is supported in your editor.
+
+${sectionLinks}
+`;
+};
+
+// Returns null if there are no docs for `section` in `docs` (mirrors the old
+// plugin's early return, meaning callers should skip generating a page).
+export const generateFullContent = (
+ version: string,
+ section: LlmsFullSection,
+ docs: Doc[],
+): string | null => {
+ const sectionDocs = docs.filter((doc) => doc.id.includes(`/${section}/`));
+ if (sectionDocs.length === 0) return null;
+
+ const docsBaseUrl = `https://metabase.com/docs/${version}`;
+
+ // Add gotcha notes for the "embedding" section if version is 57 or above
+ const gotchaSection =
+ section === "embedding" && aboveVersion(version, 57)
+ ? `${getModularEmbeddingGotchaNotes()}\n\n`
+ : "";
+
+ const documentsContent = sectionDocs
+ .map((doc) => {
+ // Strip Jekyll/Liquid template syntax
+ const content = (doc.body ?? "")
+ .replace(/\{%.*?%\}/gs, "")
+ .replace(/\{\{.*?\}\}/gs, "");
+ return `${content.trim()}\n\n---`;
+ })
+ .join("\n\n");
+
+ return `# Metabase ${section.charAt(0).toUpperCase() + section.slice(1)} - Complete Reference for AI agents
+
+> **This documentation is for Metabase ${formatVersionForDisplay(version, releaseBranch)}.**
+>
+> Table of contents: ${docsBaseUrl}/llms.txt
+
+${getVersionDetectionInstructions()}
+
+${gotchaSection}${documentsContent}
+`;
+};
diff --git a/src/lib/docs/resolveDoc.ts b/src/lib/docs/resolveDoc.ts
new file mode 100644
index 0000000000..38de3749f7
--- /dev/null
+++ b/src/lib/docs/resolveDoc.ts
@@ -0,0 +1,29 @@
+// Derives a doc's version/slug/URL from its content collection id (or
+// frontmatter `permalink` override), since docs are stored as
+// `/.md` but need a canonical `/docs//` URL for
+// routing, sitemaps, and redirects.
+export const resolveDocUrl = ({
+ id,
+ permalink,
+ includeTrailingIndex,
+}: {
+ id: string;
+ permalink?: string;
+ includeTrailingIndex?: boolean;
+}): { version: string; slug: string; url: string } => {
+ let resolvedId = (permalink?.replace(/^\/docs\//, "") ?? id).replace(
+ /\.html$/,
+ "",
+ );
+ if (!includeTrailingIndex) {
+ resolvedId = resolvedId.replace(/index$/, "");
+ }
+ const separatorIndex = resolvedId.indexOf("/");
+ const version =
+ (separatorIndex !== -1
+ ? resolvedId.slice(0, separatorIndex)
+ : resolvedId) || "latest";
+ const slug =
+ separatorIndex !== -1 ? resolvedId.slice(separatorIndex + 1) : "";
+ return { version, slug, url: `/docs/${version}/${slug}` };
+};
diff --git a/src/lib/docs/versionSupport.ts b/src/lib/docs/versionSupport.ts
new file mode 100644
index 0000000000..ea2e1da06e
--- /dev/null
+++ b/src/lib/docs/versionSupport.ts
@@ -0,0 +1,65 @@
+// Looks up support status for a docs version (e.g. "v0.63") against
+// _data/major_version_support.json, refreshed nightly from the
+// `major_version_support` key of https://static.metabase.com/version-info.json
+// by .github/workflows/update-version-support.yml
+//
+// Mirrors the logic previously provided by
+// _plugins/jekyll_version_support_plugin.rb, which built a
+// site.data.version_support lookup table at Jekyll build time.
+//
+// The data file only tracks the most recent majors, so anything older than
+// the oldest tracked major is unsupported. Versions with no entry and no
+// verdict (such as "latest" and "master") return null.
+
+import majorVersionSupport from "../../../_data/major_version_support.json";
+
+type MajorVersionSupportEntry = {
+ major: number;
+ released?: string;
+ lts?: boolean;
+ eol?: string;
+};
+
+export type VersionSupport = {
+ status: "supported" | "unsupported";
+ lts: boolean;
+};
+
+const entries = majorVersionSupport as MajorVersionSupportEntry[];
+const byMajor = new Map(entries.map((entry) => [entry.major, entry]));
+const oldestTracked = Math.min(...byMajor.keys());
+
+// "v0.63" -> 63
+const majorOf = (version: string): number | null => {
+ const match = /^v\d+\.(\d+)$/.exec(version);
+ return match ? Number(match[1]) : null;
+};
+
+export const getVersionSupport = (version: string): VersionSupport | null => {
+ const major = majorOf(version);
+ if (major === null) return null;
+
+ const entry = byMajor.get(major);
+ if (!entry) {
+ return major < oldestTracked ? { status: "unsupported", lts: false } : null;
+ }
+
+ const eol = entry.eol ? new Date(entry.eol) : null;
+ const status =
+ !eol || eol.getTime() > Date.now() ? "supported" : "unsupported";
+
+ return { status, lts: entry.lts ?? false };
+};
+
+// Builds the full version -> support lookup table (e.g. for site.data.version_support
+// in the Liquid context), mirroring VersionSupportGenerator#generate.
+export const buildVersionSupportTable = (
+ availableVersions: string[],
+): Record => {
+ const table: Record = {};
+ for (const version of availableVersions ?? []) {
+ const support = getVersionSupport(version);
+ if (support) table[version] = support;
+ }
+ return table;
+};
diff --git a/src/lib/fn.ts b/src/lib/fn.ts
new file mode 100644
index 0000000000..91d3d2e8ac
--- /dev/null
+++ b/src/lib/fn.ts
@@ -0,0 +1,4 @@
+export const compose =
+ (...fns: ((arg: T) => T)[]) =>
+ (initialValue: T) =>
+ fns.reduceRight((acc, fn) => fn(acc), initialValue);
diff --git a/src/lib/liquid/liquidRenderer.ts b/src/lib/liquid/liquidRenderer.ts
index deed1d438b..e9bdab02a4 100644
--- a/src/lib/liquid/liquidRenderer.ts
+++ b/src/lib/liquid/liquidRenderer.ts
@@ -1,9 +1,45 @@
import fs from "node:fs";
import path from "node:path";
-import { Liquid } from "liquidjs";
+import { buildVersionSupportTable } from "@/lib/docs/versionSupport";
+import { compose } from "@/lib/fn";
+import { Liquid, ParseError, TokenizationError } from "liquidjs";
import YAML from "yamljs";
+import { registerCustomIncludeTag } from "./tags/customIncludeTag";
import { registerIncludeFileTag } from "./tags/includeFileTag";
+// Old markdown docs sometimes contain text that merely looks like Liquid
+// (e.g. "{{#...}}" used to describe template tag syntax) but isn't valid
+// Liquid. Jekyll/Ruby rendered these as blank rather than failing the build,
+// so on a syntax error we cut out just the offending "{{ }}"/"{% %}" span and
+// retry, instead of taking down the whole page.
+const stripInvalidLiquidSpan = (
+ source: string,
+ err: unknown,
+): string | null => {
+ if (!(err instanceof TokenizationError) && !(err instanceof ParseError)) {
+ return null;
+ }
+
+ let { begin, end } = err.token;
+ if (!(source.startsWith("{{", begin) || source.startsWith("{%", begin))) {
+ const outputOpen = source.lastIndexOf("{{", begin);
+ const tagOpen = source.lastIndexOf("{%", begin);
+ let openStart = outputOpen;
+ let closer = "}}";
+ if (tagOpen > outputOpen) {
+ openStart = tagOpen;
+ closer = "%}";
+ }
+ if (openStart === -1) return null;
+ const closeIdx = source.indexOf(closer, end);
+ if (closeIdx === -1) return null;
+ begin = openStart;
+ end = closeIdx + closer.length;
+ }
+
+ return source.slice(0, begin) + source.slice(end);
+};
+
const ROOT = process.cwd();
const INCLUDES_ROOT = path.join(ROOT, "_includes");
@@ -27,10 +63,17 @@ const loadDataDir = (dir: string): Record => {
return data;
};
+const siteConfig = YAML.parse(
+ fs.readFileSync(path.join(ROOT, "_config.yml"), "utf8"),
+);
+
const baseCtx = {
site: {
- ...YAML.parse(fs.readFileSync(path.join(ROOT, "_config.yml"), "utf8")),
- data: loadDataDir(path.join(ROOT, "_data")),
+ ...siteConfig,
+ data: {
+ ...loadDataDir(path.join(ROOT, "_data")),
+ version_support: buildVersionSupportTable(siteConfig.available_versions),
+ },
},
jekyll: {
environment: process.env.NODE_ENV || "development",
@@ -39,6 +82,11 @@ const baseCtx = {
let liquidEngine: Liquid;
+// Remove multiple newlines between elements so satteri doesn't turn them into code snippets.
+// Needed to preserve previous behavior (which used jekyll + kramdown).
+const collapseBlankLines = (html: string): string =>
+ html.replace(/>([ \t]*\r?\n){2,}[ \t]*\n<");
+
export const getLiquidRenderer = ({
page,
dirname,
@@ -52,8 +100,12 @@ export const getLiquidRenderer = ({
jekyllInclude: true,
jekyllWhere: true,
strictVariables: false, // TODO: Would be nice to flip this to true
+ cache: import.meta.env.MODE === "production",
});
- registerIncludeFileTag(liquidEngine);
+ compose(
+ registerIncludeFileTag,
+ registerCustomIncludeTag(collapseBlankLines),
+ )(liquidEngine);
}
const ctx = {
@@ -63,14 +115,32 @@ export const getLiquidRenderer = ({
};
return {
- render: (
+ render: async (
html: string,
{ include }: { include?: Record } = {},
+ { maxSyntaxErrors = 0 }: { maxSyntaxErrors?: number } = {},
) => {
- return liquidEngine.parseAndRender(html, {
- ...ctx,
- include,
- });
+ let source = html;
+ for (let attempt = 0; attempt < maxSyntaxErrors + 1; attempt++) {
+ try {
+ return await liquidEngine.parseAndRender(source, {
+ ...ctx,
+ include,
+ });
+ } catch (err) {
+ const stripped = stripInvalidLiquidSpan(source, err);
+ if (stripped === null) throw err;
+ console.warn(
+ `[liquid] Ignoring invalid Liquid syntax in ${dirname}: ${
+ (err as Error).message
+ }`,
+ );
+ source = stripped;
+ }
+ }
+ throw new Error(
+ `[liquid] Too many invalid Liquid syntax errors in ${dirname}`,
+ );
},
};
};
diff --git a/src/lib/liquid/tags/customIncludeTag.ts b/src/lib/liquid/tags/customIncludeTag.ts
new file mode 100644
index 0000000000..9959614714
--- /dev/null
+++ b/src/lib/liquid/tags/customIncludeTag.ts
@@ -0,0 +1,27 @@
+import { IncludeTag, Liquid, type Context, type Emitter } from "liquidjs";
+
+// Overrides LiquidJS's built-in `include` tag so each included template's rendered HTML
+// can be post-processed before it's written to the main output.
+
+class BufferingEmitter implements Emitter {
+ buffer = "";
+ write(html: unknown) {
+ this.buffer += String(html);
+ }
+}
+
+export const registerCustomIncludeTag =
+ (postProcessFn: (includeHtml: string) => string) => (engine: Liquid) => {
+ class CustomIncludeTag extends IncludeTag {
+ *render(
+ ctx: Context,
+ emitter: Emitter,
+ ): Generator {
+ const buffer = new BufferingEmitter();
+ yield* super.render(ctx, buffer);
+ emitter.write(postProcessFn(buffer.buffer));
+ }
+ }
+ engine.registerTag("include", CustomIncludeTag);
+ return engine;
+ };
diff --git a/src/lib/markdown/markdownRenderer.ts b/src/lib/markdown/markdownRenderer.ts
index a6f0c275cb..0c045ce88f 100644
--- a/src/lib/markdown/markdownRenderer.ts
+++ b/src/lib/markdown/markdownRenderer.ts
@@ -1,13 +1,15 @@
import { satteri } from "@astrojs/markdown-satteri";
+import { codeDefaultsHastPlugin } from "./plugins/codeDefaultsHastPlugin";
import { ialHastPlugin } from "./plugins/ialHastPlugin";
-import { inlineCodeHastPlugin } from "./plugins/inlineCodeHastPlugin";
+import { relativeImagePlugin } from "./plugins/relativeImagePlugin";
import { responsiveTableLabelsHastPlugin } from "./plugins/responsiveTableLabelsHastPlugin";
const docsMarkdownProcessor = satteri({
hastPlugins: [
ialHastPlugin,
- inlineCodeHastPlugin,
+ codeDefaultsHastPlugin,
responsiveTableLabelsHastPlugin,
+ relativeImagePlugin,
],
});
diff --git a/src/lib/markdown/noopMarkdownProcessor.ts b/src/lib/markdown/noopMarkdownProcessor.ts
new file mode 100644
index 0000000000..b604bb598d
--- /dev/null
+++ b/src/lib/markdown/noopMarkdownProcessor.ts
@@ -0,0 +1,17 @@
+import type { MarkdownProcessor } from "astro/markdown";
+
+export const noopMarkdownProcessor: MarkdownProcessor = {
+ name: "no-op",
+ options: {},
+ createRenderer: async () => ({
+ render: async () => ({
+ code: "",
+ metadata: {
+ headings: [],
+ localImagePaths: [],
+ remoteImagePaths: [],
+ frontmatter: {},
+ },
+ }),
+ }),
+};
diff --git a/src/lib/markdown/plugins/codeDefaultsHastPlugin.ts b/src/lib/markdown/plugins/codeDefaultsHastPlugin.ts
new file mode 100644
index 0000000000..8bf3f20a96
--- /dev/null
+++ b/src/lib/markdown/plugins/codeDefaultsHastPlugin.ts
@@ -0,0 +1,42 @@
+import { defineHastPlugin } from "satteri";
+
+// Kramdown/Rouge (the old Jekyll pipeline) defaulted undeclared-language
+// code to a plaintext lexer; Sätteri leaves it bare instead. Two knock-on
+// effects this restores:
+// - Inline spans get `language-plaintext highlighter-rouge` unconditionally,
+// since js/new-docs-code-snippet-copy.js skips the copy-button overlay on
+// `language-plaintext` and js/syntax-highlight.js only highlights
+// `.highlighter-rouge` elements.
+// - Fenced blocks with no declared language get hljs's own `nohighlight`
+// marker instead, so `highlightAll()` doesn't auto-detect (and sometimes
+// misdetect, e.g. a table read as SQL) a language for them. This is kept
+// distinct from `language-plaintext` so blocks still get a copy button —
+// only inline spans should lose it.
+export const codeDefaultsHastPlugin = defineHastPlugin({
+ name: "code-defaults",
+ element: {
+ filter: ["code"],
+ visit(node, ctx) {
+ const parent = ctx.parent(node);
+ const isBlock =
+ !!parent && "tagName" in parent && parent.tagName === "pre";
+ const existing = Array.isArray(node.properties?.className)
+ ? (node.properties.className as unknown[])
+ : [];
+
+ if (isBlock) {
+ const hasLanguage = existing.some(
+ (cls) => typeof cls === "string" && cls.startsWith("language-"),
+ );
+ if (hasLanguage) return;
+ ctx.setProperty(node, "className", [...existing, "nohighlight"]);
+ } else {
+ ctx.setProperty(node, "className", [
+ ...existing,
+ "language-plaintext",
+ "highlighter-rouge",
+ ]);
+ }
+ },
+ },
+});
diff --git a/src/lib/markdown/plugins/inlineCodeHastPlugin.ts b/src/lib/markdown/plugins/inlineCodeHastPlugin.ts
deleted file mode 100644
index 32d1b8d856..0000000000
--- a/src/lib/markdown/plugins/inlineCodeHastPlugin.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { defineHastPlugin } from "satteri";
-
-// Kramdown (Jekyll's Markdown converter) routes every code span through its
-// syntax highlighter (Rouge in Jekyll's config), even inline ones with no
-// declared language — Rouge falls back to its plaintext lexer and kramdown
-// wraps the result as ``.
-// CommonMark/Sätteri has no such hook for inline code (only fenced blocks
-// carry a language), so plain `` comes out bare. Two site scripts rely
-// on kramdown's classes being there: js/syntax-highlight.js only
-// syntax-highlights `.highlighter-rouge` elements, and
-// js/new-docs-code-snippet-copy.js attaches a copy-button overlay to every
-// `` *except* ones classed `language-plaintext` — without this plugin,
-// every inline code span across the site would get a copy button.
-export const inlineCodeHastPlugin = defineHastPlugin({
- name: "inline-code",
- element: {
- filter: ["code"],
- visit(node, ctx) {
- const parent = ctx.parent(node);
- if (parent && "tagName" in parent && parent.tagName === "pre") return;
- const existing = Array.isArray(node.properties?.className)
- ? (node.properties.className as unknown[])
- : [];
- ctx.setProperty(node, "className", [
- ...existing,
- "language-plaintext",
- "highlighter-rouge",
- ]);
- },
- },
-});
diff --git a/src/lib/markdown/plugins/relativeImagePlugin.ts b/src/lib/markdown/plugins/relativeImagePlugin.ts
new file mode 100644
index 0000000000..3a42f3ba94
--- /dev/null
+++ b/src/lib/markdown/plugins/relativeImagePlugin.ts
@@ -0,0 +1,28 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DOCS_SRC_ROOT } from "@/constants";
+import { defineHastPlugin } from "satteri";
+
+// Resolves relative images from docs md files.
+// The images themselves are copied via viteStaticCopy in astro.config.mjs.
+
+export const relativeImagePlugin = defineHastPlugin({
+ name: "relative-image-resolver",
+ element: {
+ filter: ["img"],
+ visit(node, ctx) {
+ const rawSrc = node.properties?.src;
+ if (typeof rawSrc !== "string" || rawSrc === "") return;
+ // Absolute site paths, absolute URLs, and data: URIs need no rewriting.
+ if (rawSrc.startsWith("/") || URL.canParse(rawSrc)) return;
+ if (!ctx.fileURL) return;
+
+ const absPath = fileURLToPath(new URL(decodeURI(rawSrc), ctx.fileURL));
+ const relPath = path.relative(DOCS_SRC_ROOT, absPath);
+ if (relPath.startsWith("..") || path.isAbsolute(relPath)) return;
+
+ const newSrc = `/docs/${relPath.split(path.sep).map(encodeURIComponent).join("/")}`;
+ ctx.setProperty(node, "src", newSrc);
+ },
+ },
+});
diff --git a/src/pages/docs/[version]/[...slug].astro b/src/pages/docs/[version]/[...slug].astro
new file mode 100644
index 0000000000..46e60ca6a5
--- /dev/null
+++ b/src/pages/docs/[version]/[...slug].astro
@@ -0,0 +1,76 @@
+---
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import NewDocsLayout from "@/layouts/NewDocsLayout.astro";
+import OldDocsLayout from "@/layouts/OldDocsLayout.astro";
+import { resolveDocUrl } from "@/lib/docs/resolveDoc";
+import { getLiquidRenderer } from "@/lib/liquid/liquidRenderer";
+import { getMarkdownRenderer } from "@/lib/markdown/markdownRenderer";
+import { getCollection, type DataEntryMap } from "astro:content";
+
+type Props =
+ | { kind: "md"; doc: DataEntryMap["docs"][number] }
+ | { kind: "html"; doc: DataEntryMap["docsHtml"][number] };
+
+export const getStaticPaths = async () => {
+ const [docs, docsHtml] = await Promise.all([
+ getCollection("docs"),
+ getCollection("docsHtml"),
+ ]);
+
+ const toPath =
+ (kind: Kind) =>
+ (doc: { id: string; data: { permalink?: string } }) => {
+ const { version, slug } = resolveDocUrl({
+ id: doc.id,
+ permalink: doc.data.permalink,
+ // For prod builds, we want to output like folder/index.html, but for the dev server, the route should exclude /index
+ includeTrailingIndex: import.meta.env.MODE !== "development",
+ });
+ return { props: { kind, doc }, params: { version, slug } };
+ };
+
+ return [...docs.map(toPath("md")), ...docsHtml.map(toPath("html"))];
+};
+
+const { version, slug = "" } = Astro.params;
+const { kind, doc } = Astro.props;
+const dirname = path.dirname(doc.filePath!);
+
+// Process liquid first (e.g. control flow, includes, variables, etc)
+const lq = getLiquidRenderer({ page: doc.data, dirname });
+const lqOutput = await lq.render(doc.body!, undefined, {
+ maxSyntaxErrors: version === "latest" ? 0 : 3,
+});
+
+// `.html` docs (TypeDoc SDK API reference pages, api.html ToC pages) are
+// already complete standalone HTML documents — only Liquid needs to run on
+// them (e.g. the embedded-analytics-sdk-metadata include), no markdown
+// conversion, and no NewDocsLayout chrome (mirrors the old Jekyll
+// `docs-api` layout, which was a bare passthrough).
+let renderedHtml: string;
+if (kind === "html") {
+ renderedHtml = lqOutput;
+} else {
+ const md = await getMarkdownRenderer();
+ const renderResult = await md.render(lqOutput, {
+ fileURL: pathToFileURL(path.resolve(doc.filePath!)),
+ });
+ renderedHtml = renderResult.code;
+}
+
+const Layout = doc.data.layout === "docs" ? OldDocsLayout : NewDocsLayout;
+---
+
+{
+ kind === "html" ? (
+
+ ) : (
+
+
+
+ )
+}
diff --git a/src/pages/docs/[version]/llms-[section]-full.txt.ts b/src/pages/docs/[version]/llms-[section]-full.txt.ts
new file mode 100644
index 0000000000..e2ad002540
--- /dev/null
+++ b/src/pages/docs/[version]/llms-[section]-full.txt.ts
@@ -0,0 +1,30 @@
+import {
+ generateFullContent,
+ getDocsByVersion,
+ getFullSections,
+ type Doc,
+ type LlmsFullSection,
+} from "@/lib/docs/llmsTxt";
+import type { APIRoute, GetStaticPaths } from "astro";
+
+export const getStaticPaths: GetStaticPaths = async () => {
+ const docsByVersion = await getDocsByVersion();
+ return [...docsByVersion.entries()].flatMap(([version, docs]) =>
+ getFullSections(docs).map((section) => ({
+ params: { version, section },
+ props: { docs },
+ })),
+ );
+};
+
+export const GET: APIRoute = async ({ params, props }) => {
+ const { docs } = props as { docs: Doc[] };
+ const content = generateFullContent(
+ params.version!,
+ params.section as LlmsFullSection,
+ docs,
+ )!;
+ return new Response(content, {
+ headers: { "Content-Type": "text/plain; charset=utf-8" },
+ });
+};
diff --git a/src/pages/docs/[version]/llms.txt.ts b/src/pages/docs/[version]/llms.txt.ts
new file mode 100644
index 0000000000..8aae2d778d
--- /dev/null
+++ b/src/pages/docs/[version]/llms.txt.ts
@@ -0,0 +1,21 @@
+import {
+ generateIndexContent,
+ getDocsByVersion,
+ type Doc,
+} from "@/lib/docs/llmsTxt";
+import type { APIRoute, GetStaticPaths } from "astro";
+
+export const getStaticPaths: GetStaticPaths = async () => {
+ const docsByVersion = await getDocsByVersion();
+ return [...docsByVersion.entries()].map(([version, docs]) => ({
+ params: { version },
+ props: { docs },
+ }));
+};
+
+export const GET: APIRoute = async ({ params, props }) => {
+ const { docs } = props as { docs: Doc[] };
+ return new Response(generateIndexContent(params.version!, docs), {
+ headers: { "Content-Type": "text/plain; charset=utf-8" },
+ });
+};
diff --git a/src/pages/docs/astro-test/[...slug].astro b/src/pages/docs/astro-test/[...slug].astro
deleted file mode 100644
index 88eb3d98eb..0000000000
--- a/src/pages/docs/astro-test/[...slug].astro
+++ /dev/null
@@ -1,41 +0,0 @@
----
-import NewDocsLayout from "@/layouts/NewDocsLayout.astro";
-import { getLiquidRenderer } from "@/lib/liquid/liquidRenderer";
-import { getMarkdownRenderer } from "@/lib/markdown/markdownRenderer";
-import { getCollection, type DataEntryMap } from "astro:content";
-
-type Props = {
- example: DataEntryMap["examples"][number];
-};
-
-export const getStaticPaths = async () => {
- const examples = await getCollection("examples");
- return [
- ...examples.map((example) => ({
- props: { example },
- params: { slug: example.id.replace(/^src\//, "") },
- })),
- ];
-};
-
-const { example } = Astro.props;
-
-// This is for debug purposes only. When rendering _docs, the dirname will be the source md file's path.
-const dirname = "_docs/latest/embedding";
-
-// Process liquid first (e.g. control flow, includes, variables, etc)
-const lq = getLiquidRenderer({ page: example.data, dirname });
-const lqOutput = await lq.render(example.body!);
-
-// Remove whitespace between elements so satteri doesn't turn them into code snippets.
-// Mimics previous behavior (which used jekyll + kramdown).
-const lqProcessed = lqOutput.replace(/>\s+<");
-
-// Convert processed markdown to html
-const md = await getMarkdownRenderer();
-const renderResult = await md.render(lqProcessed);
----
-
-
-
-
diff --git a/src/pages/docs/sitemap.xml.ts b/src/pages/docs/sitemap.xml.ts
new file mode 100644
index 0000000000..695305541c
--- /dev/null
+++ b/src/pages/docs/sitemap.xml.ts
@@ -0,0 +1,31 @@
+import { resolveDocUrl } from "@/lib/docs/resolveDoc";
+import type { APIRoute } from "astro";
+import { getCollection } from "astro:content";
+
+const SITE_URL = import.meta.env.SITE;
+
+const isLatest = ({ id }: { id: string }) =>
+ id === "latest" || id.startsWith("latest/");
+
+export const GET: APIRoute = async () => {
+ const [docs, docsHtml] = await Promise.all([
+ getCollection("docs", isLatest),
+ getCollection("docsHtml", isLatest),
+ ]);
+
+ const paths = [...docs, ...docsHtml]
+ .map(
+ (doc) => resolveDocUrl({ id: doc.id, permalink: doc.data.permalink }).url,
+ )
+ .sort();
+
+ const body = `
+
+${paths.map((path) => ` \n ${`${SITE_URL}${path}`}\n `).join("\n")}
+
+`;
+
+ return new Response(body, {
+ headers: { "Content-Type": "application/xml" },
+ });
+};