refactor: split docusaurus config in files

build: enable docusaurus "experimental_faster"
build: enable docusaurus v4 features
refactor: update autogen indexer tables
refactor: use typescript for "redirects"
refactor: various improvements
style: fix indenting for code snippets

Author: PaulRBerg

.gitignore

@@ -1,9 +1,9 @@
 # directories
 .cache-loader
 .docusaurus
+.repomix
 build
 node_modules
-repomix
 src/autogen/**/*.mdx
 
 # files

.vscode/settings.json

@@ -1,11 +1,11 @@
 {
   "biome.enabled": true,
+  "eslint.validate": ["md", "mdx"],
+  "typescript.tsdk": "node_modules/typescript/lib",
   "editor.codeActionsOnSave": {
     "source.fixAll.biome": "explicit",
     "source.organizeImports.biome": "explicit"
   },
-  "eslint.validate": ["md", "mdx"],
-  "typescript.tsdk": "node_modules/typescript/lib",
   "search.exclude": {
     ".docusaurus": true,
     "build": true,

babel.config.js

@@ -21,59 +21,59 @@ export async function generateIndexers(options: CliOptions = {}): Promise<void>
 }
 
 function generateTables(protocol: Indexer.Protocol, options: CliOptions): void {
-  const graphTable = generateGraphTable(indexers.graph[protocol]);
   const envioTable = generateEnvioTable(indexers.envio[protocol]);
+  const graphTable = generateGraphTable(indexers.graph[protocol]);
+
+  const envioFilePath = autogenFilePaths.envio(protocol);
+  if (writeFileWithOverwrite({ content: envioTable, filePath: envioFilePath, options })) {
+    console.log(`✔️  Generated ${_.capitalize(protocol)} endpoints table for Envio at: ${getRelative(envioFilePath)}`);
+  }
 
   const graphFilePath = autogenFilePaths.graph(protocol);
   if (writeFileWithOverwrite({ content: graphTable, filePath: graphFilePath, options })) {
     console.log(
       `✔️  Generated ${_.capitalize(protocol)} endpoints table for The Graph at: ${getRelative(graphFilePath)}`,
     );
   }
-
-  const envioFilePath = autogenFilePaths.envio(protocol);
-  if (writeFileWithOverwrite({ content: envioTable, filePath: envioFilePath, options })) {
-    console.log(`✔️  Generated ${_.capitalize(protocol)} endpoints table for Envio at: ${getRelative(envioFilePath)}`);
-  }
 }
 
-function generateGraphTable(indexers: Indexer[]): string {
-  let markdown = `| Chain | Production URL | Testing URL | Explorer URL |\n`;
+function generateEnvioTable(indexers: Indexer[]): string {
+  let markdown = `| Chain | Production URL | Playground URL | Explorer URL |\n`;
   markdown += `| -------- | -------------- | ----------- | ------------ |\n`;
 
   for (const indexer of indexers) {
-    const chain = sablier.chains.getOrThrow(indexer.chainId);
+    const chain = sablier.chains.get(indexer.chainId);
+    if (!chain || !chain.name) {
+      continue;
+    }
 
     const productionURL = indexer.endpoint.url;
-    const testingURL = indexer.testingURL;
+    const playgroundURL = indexer.testingURL;
     const explorerURL = indexer.explorerURL;
 
-    const productionCell = `[${indexer.name}](${productionURL})`;
-    const testingCell = testingURL ? `[Testing](${testingURL})` : "N/A";
+    const productionCell = `${productionURL}`;
+    const playgroundCell = playgroundURL ? `[Playground](${playgroundURL})` : "N/A";
     const explorerCell = explorerURL ? `[Explorer](${explorerURL})` : "N/A";
 
-    markdown += `| ${chain.name} | ${productionCell} | ${testingCell} | ${explorerCell} |\n`;
+    markdown += `| ${chain.name} | ${productionCell} | ${playgroundCell} | ${explorerCell} |\n`;
   }
 
   return markdown;
 }
 
-function generateEnvioTable(indexers: Indexer[]): string {
+function generateGraphTable(indexers: Indexer[]): string {
   let markdown = `| Chain | Production URL | Testing URL | Explorer URL |\n`;
   markdown += `| -------- | -------------- | ----------- | ------------ |\n`;
 
   for (const indexer of indexers) {
-    const chain = sablier.chains.get(indexer.chainId);
-    if (!chain || !chain.name) {
-      continue;
-    }
+    const chain = sablier.chains.getOrThrow(indexer.chainId);
 
     const productionURL = indexer.endpoint.url;
     const testingURL = indexer.testingURL;
     const explorerURL = indexer.explorerURL;
 
-    const productionCell = `${productionURL}`;
-    const testingCell = `[Testing](${testingURL})`;
+    const productionCell = `[${indexer.name}](${productionURL})`;
+    const testingCell = testingURL ? `[Testing](${testingURL})` : "N/A";
     const explorerCell = explorerURL ? `[Explorer](${explorerURL})` : "N/A";
 
     markdown += `| ${chain.name} | ${productionCell} | ${testingCell} | ${explorerCell} |\n`;

bun.lock

@@ -0,0 +1,22 @@
+import type { Options as ClientRedirectsOptions } from "@docusaurus/plugin-client-redirects";
+import type { Options as VercelAnalyticsOptions } from "@docusaurus/plugin-vercel-analytics";
+import { type DocusaurusConfig } from "@docusaurus/types";
+import { createRedirects, redirects } from "./redirects";
+
+const clientRedirects: [string, ClientRedirectsOptions] = [
+  "@docusaurus/plugin-client-redirects",
+  {
+    createRedirects,
+    id: "default",
+    redirects: redirects,
+  },
+];
+
+const vercelAnalytics: [string, VercelAnalyticsOptions] = [
+  "vercel-analytics",
+  {
+    mode: "auto",
+  },
+];
+
+export const plugins: DocusaurusConfig["plugins"] = [clientRedirects, vercelAnalytics];

cli/commands/autogen/indexers.ts

@@ -0,0 +1,23 @@
+import type * as Preset from "@docusaurus/preset-classic";
+import type { DocusaurusConfig } from "@docusaurus/types";
+import rehypeKatex from "rehype-katex";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+
+const classic: [string, Preset.Options] = [
+  "classic",
+  {
+    docs: {
+      editUrl: "https://github.com/sablier-labs/docs/blob/main/",
+      rehypePlugins: [rehypeKatex],
+      remarkPlugins: [remarkGfm, remarkMath],
+      routeBasePath: "/", // Serve the docs at the site's root
+      sidebarPath: "./config/sidebars.ts",
+    },
+    theme: {
+      customCss: ["./src/css/sablier.css", "./src/css/custom.css"],
+    },
+  },
+];
+
+export const presets: DocusaurusConfig["presets"] = [classic];

config/plugins.ts

@@ -0,0 +1,99 @@
+import type { RedirectOption } from "@docusaurus/plugin-client-redirects/lib/options";
+
+function redirect(from: string, to: string): RedirectOption {
+  return { from, to };
+}
+
+/**
+ * The slugs and IDs used in the Docusaurus site have evolved over time.
+ * This file contains the redirects for the old slugs and IDs to the new ones.
+ */
+export const redirects: RedirectOption[] = [
+  /* -------------------------------------------------------------------------- */
+  /*                                  AIRDROPS                                  */
+  /* -------------------------------------------------------------------------- */
+  redirect("/concepts/merkle-airdrops", "/concepts/airdrops"),
+  /* -------------------------------------------------------------------------- */
+  /*                                     API                                    */
+  /* -------------------------------------------------------------------------- */
+  redirect("/api", "/api/overview"),
+  // TODO: change this to the new GraphQL section
+  redirect("/api/airdrops/the-graph", "/api/overview"),
+  redirect("/api/indexers/protocol", "/api/overview"),
+  redirect("/api/lockup/the-graph", "/api/overview"),
+  redirect("/api/merkle-api/intro", "/api/airdrops/merkle-api/overview"),
+  redirect("/api/subgraphs/endpoints", "/api/lockup/indexers"),
+  redirect("/api/subgraphs/merkle", "/api/overview"),
+  redirect("/api/subgraphs/overview", "/api/overview"),
+  redirect("/api/subgraphs/protocol", "/api/overview"),
+  /* -------------------------------------------------------------------------- */
+  /*                                    APPS                                    */
+  /* -------------------------------------------------------------------------- */
+  redirect("/apps", "/apps/features/overview"),
+  redirect("/apps/csv-support", "/apps/guides/csv-support"),
+  redirect("/apps/features", "/apps/features/vesting"),
+  redirect("/apps/features/airstreams", "/apps/features/airdrops"),
+  redirect("/apps/features/general", "/apps/features/overview"),
+  redirect("/apps/features/streams", "/apps/features/vesting"),
+  redirect("/apps/overview", "/apps/features/overview"),
+  redirect("/apps/support/how-to", "/support/how-to"),
+  redirect("/apps/url-schemes", "/apps/guides/url-schemes"),
+  /* -------------------------------------------------------------------------- */
+  /*                                  INDEXERS                                  */
+  /* -------------------------------------------------------------------------- */
+  redirect("/api/airdrops/endpoints", "/api/airdrops/indexers"),
+  redirect("/api/flow/endpoints", "/api/flow/indexers"),
+  redirect("/api/lockup/endpoints", "/api/lockup/indexers"),
+  /* -------------------------------------------------------------------------- */
+  /*                              LEGACY: 2019-2021                             */
+  /* -------------------------------------------------------------------------- */
+  redirect("/protocol/faq/basics", "/concepts/what-is-sablier"),
+  redirect("/protocol/guides/chains", "/guides/legacy/overview"),
+  redirect("/protocol/guides/getting-started", "/guides/legacy/overview"),
+  redirect("/protocol/introduction", "/concepts/what-is-sablier"),
+  redirect("/protocol/subgraphs/endpoints", "/api/overview"),
+  redirect("/contracts/v1/deployments", "/guides/legacy/deployments"),
+  redirect("/contracts/v1/guides/getting-started", "/guides/legacy/overview"),
+  redirect("/contracts/v1/overview", "/guides/legacy/overview"),
+  /* -------------------------------------------------------------------------- */
+  /*                          LOCKUP: 2024 and Earlier                          */
+  /* -------------------------------------------------------------------------- */
+  redirect("/concepts/protocol/fees", "/concepts/fees"),
+  redirect("/concepts/protocol/nft", "/concepts/nft"),
+  redirect("/concepts/protocol/stream-types", "/concepts/lockup/stream-shapes"),
+  redirect("/concepts/protocol/streaming", "/concepts/streaming"),
+  redirect("/concepts/protocol/transferability", "/concepts/transferability"),
+  redirect("/concepts/sablier-protocol", "/concepts/what-is-sablier"),
+  redirect("/contracts/v2/deployments/v2.0", "/guides/lockup/previous-deployments/v1.0"),
+  redirect("/contracts/v2/deployments/v2.1", "/guides/lockup/previous-deployments/v1.1"),
+  redirect("/contracts/v2/guides", "/guides/lockup/overview"),
+  redirect("/contracts/v2/reference/overview", "/reference/overview"),
+  redirect("/contracts/v2/security", "/concepts/security"),
+  redirect("/csv", "/apps/guides/csv-support"),
+];
+
+export function createRedirects(existingPath: string) {
+  const redirects = [];
+  // Redirect /concepts/protocol/** to /concepts/lockup/**
+  if (existingPath.startsWith("/concepts/lockup/")) {
+    redirects.push(existingPath.replace("/concepts/lockup/", "/concepts/protocol/"));
+  }
+  // Redirect /contracts/v1/guides/** to /guides/legacy/**
+  else if (existingPath.startsWith("/guides/legacy/")) {
+    redirects.push(existingPath.replace("/guides/legacy/", "/contracts/v1/guides/"));
+  }
+  // Redirect /contracts/v2/reference/** to /reference/lockup/**
+  else if (existingPath.startsWith("/reference/lockup/")) {
+    redirects.push(existingPath.replace("/reference/lockup/", "/contracts/v2/reference/"));
+  }
+  // Redirect /contracts/v1/** to /reference/legacy/**
+  else if (existingPath.startsWith("/reference/legacy/")) {
+    redirects.push(existingPath.replace("/reference/legacy/", "/contracts/v1/"));
+  }
+  // Redirect /contracts/v2/guides/** to /guides/lockup/examples/**
+  else if (existingPath.startsWith("/guides/lockup/examples/")) {
+    redirects.push(existingPath.replace("/guides/lockup/examples/", "/contracts/v2/guides/"));
+  }
+
+  return redirects;
+}

config/presets.ts

@@ -1,7 +1,10 @@
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-// By default, Docusaurus generates a sidebar from the docs folder structure,
-// but we can customize it to include only the desired sections.
-const sidebars = {
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+/**
+ * By default, Docusaurus generates a sidebar from the docs folder structure, but we can
+ * customize it to include only the desired sections.
+ */
+const sidebars: SidebarsConfig = {
   apiSidebar: [{ dirName: "api", type: "autogenerated" }],
   appSidebar: [{ dirName: "apps", type: "autogenerated" }],
   conceptsSidebar: [{ dirName: "concepts", type: "autogenerated" }],