@docusaurus/types 3.9.2-canary-6437 → 3.9.2-canary-6439

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/types",
-  "version": "3.9.2-canary-6437",
+  "version": "3.9.2-canary-6439",
   "description": "Common types for Docusaurus packages.",
   "types": "./src/index.d.ts",
   "publishConfig": {
@@ -28,5 +28,5 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
-  "gitHead": "c36f3ac2e06fc332b02fc2feaae5011d1a51ac87"
+  "gitHead": "67795b9b8e2c6d94284ae736bb0d974a2cf2000b"
 }

package/src/config.d.ts

@@ -33,6 +33,7 @@ export type FasterConfig = {
   rspackBundler: boolean;
   rspackPersistentCache: boolean;
   ssgWorkerThreads: boolean;
+  gitEagerVcs: boolean;
 };
 
 export type FutureV4Config = {
@@ -40,6 +41,53 @@ export type FutureV4Config = {
   useCssCascadeLayers: boolean;
 };
 
+// VCS (Version Control System) info about a given change, e.g., a git commit.
+// The agnostic term "VCS" is used instead of "git" to acknowledge the existence
+// of other version control systems, and external systems like CMSs and i18n
+// translation SaaS (e.g., Crowdin)
+export type VcsChangeInfo = {timestamp: number; author: string};
+
+export type VscInitializeParams = {
+  siteDir: string;
+  // TODO could it be useful to provide all plugins getPathsToWatch() here?
+  //  this could give the opportunity to find out all VCS roots ahead of times
+  //  this is mostly useful for multi-git-repo setups, can be added later
+};
+
+// VCS (Version Control System) config hooks to get file change info.
+// This lets you override and customize the default Docusaurus behavior.
+// This can be useful to optimize calls or when using something else than git
+// See https://github.com/facebook/docusaurus/issues/11208
+// See https://github.com/e18e/ecosystem-issues/issues/216
+export type VcsConfig = {
+  /**
+   * Initialize the VCS system.
+   * This is notably useful to pre-read eagerly a full Git repository so that
+   * all the files first/last update info can be retrieved efficiently later
+   *
+   * Note: for now, this function is synchronous on purpose, it can be used to
+   * start warming up the VCS by reading eagerly, but we don't want to delay
+   * the rest of the Docusaurus start/build process. Instead of awaiting the
+   * init promise, you can create/store it and await it later during reads.
+   *
+   * @param params Initialization params that can be useful to warm up the VCS
+   */
+  initialize: (params: VscInitializeParams) => void;
+  getFileCreationInfo: (filePath: string) => Promise<VcsChangeInfo | null>;
+  getFileLastUpdateInfo: (filePath: string) => Promise<VcsChangeInfo | null>;
+};
+
+/**
+ * List of pre-built VcsConfig that Docusaurus provides.
+ */
+export type VcsPreset =
+  | 'git-ad-hoc'
+  | 'git-eager'
+  | 'hardcoded'
+  | 'disabled'
+  | 'default-v1'
+  | 'default-v2';
+
 export type FutureConfig = {
   /**
    * Turns v4 future flags on
@@ -50,6 +98,8 @@ export type FutureConfig = {
 
   experimental_storage: StorageConfig;
 
+  experimental_vcs: VcsConfig;
+
   /**
    * Docusaurus can work with 2 router types.
    *
@@ -367,6 +417,7 @@ export type Config = Overwrite<
       {
         v4?: boolean | Partial<FutureV4Config>;
         experimental_faster?: boolean | Partial<FasterConfig>;
+        experimental_vcs?: VcsPreset | VcsConfig | boolean;
       }
     >;
   }

package/src/index.d.ts

@@ -13,6 +13,10 @@ export {
   FutureV4Config,
   FasterConfig,
   StorageConfig,
+  VcsConfig,
+  VcsPreset,
+  VcsChangeInfo,
+  VscInitializeParams,
   Config,
 } from './config';