@docusaurus/types 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/types",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Common types for Docusaurus packages.",
   "types": "./src/index.d.ts",
   "publishConfig": {
@@ -27,5 +27,5 @@
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   },
-  "gitHead": "a5e675821f0e8b70b591fcebf19fd60a70d55548"
+  "gitHead": "5af143651b26b39761361acd96e9c5be7ba0cb25"
 }

package/src/context.d.ts

@@ -31,6 +31,7 @@ export type GlobalData = {[pluginName: string]: {[pluginId: string]: unknown}};
 
 export type LoadContext = {
   siteDir: string;
+  siteVersion: string | undefined;
   generatedFilesDir: string;
   siteConfig: DocusaurusConfig;
   siteConfigPath: string;

package/src/index.d.ts

@@ -45,6 +45,7 @@ export {
 
 export {
   Plugin,
+  PluginIdentifier,
   InitializedPlugin,
   LoadedPlugin,
   PluginModule,
@@ -69,6 +70,7 @@ export {
 
 export {
   RouteConfig,
+  RouteMetadata,
   RouteContext,
   PluginRouteContext,
   Registry,

package/src/plugin.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {TranslationFile} from './i18n';
+import type {CodeTranslations, TranslationFile} from './i18n';
 import type {RuleSetRule, Configuration as WebpackConfiguration} from 'webpack';
 import type {CustomizeRuleString} from 'webpack-merge/dist/types';
 import type {CommanderStatic} from 'commander';
@@ -18,11 +18,11 @@ import type {RouteConfig} from './routing';
 
 export type PluginOptions = {id?: string} & {[key: string]: unknown};
 
-export type PluginConfig =
+export type PluginConfig<Content = unknown> =
   | string
   | [string, PluginOptions]
-  | [PluginModule, PluginOptions]
-  | PluginModule
+  | [PluginModule<Content>, PluginOptions]
+  | PluginModule<Content>
   | false
   | null;
 
@@ -110,7 +110,9 @@ export type Plugin<Content = unknown> = {
   contentLoaded?: (args: {
     /** The content loaded by this plugin instance */
     content: Content; //
-    /** Content loaded by ALL the plugins */
+    actions: PluginContentLoadedActions;
+  }) => Promise<void> | void;
+  allContentLoaded?: (args: {
     allContent: AllContent;
     actions: PluginContentLoadedActions;
   }) => Promise<void> | void;
@@ -163,6 +165,15 @@ export type Plugin<Content = unknown> = {
   }) => ThemeConfig;
 };
 
+/**
+ * Data required to uniquely identify a plugin
+ * The name or instance id alone is not enough
+ */
+export type PluginIdentifier = {
+  readonly name: string;
+  readonly id: string;
+};
+
 export type InitializedPlugin = Plugin & {
   readonly options: Required<PluginOptions>;
   readonly version: PluginVersionInformation;
@@ -172,10 +183,15 @@ export type InitializedPlugin = Plugin & {
 
 export type LoadedPlugin = InitializedPlugin & {
   readonly content: unknown;
+  readonly globalData: unknown;
+  readonly routes: RouteConfig[];
+  readonly defaultCodeTranslations: CodeTranslations;
 };
 
-export type PluginModule = {
-  (context: LoadContext, options: unknown): Plugin | Promise<Plugin>;
+export type PluginModule<Content = unknown> = {
+  (context: LoadContext, options: unknown):
+    | Plugin<Content>
+    | Promise<Plugin<Content>>;
   validateOptions?: <T, U>(data: OptionValidationContext<T, U>) => U;
   validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;
 

package/src/routing.d.ts

@@ -11,7 +11,7 @@ import type {ParsedUrlQueryInput} from 'querystring';
  * A "module" represents a unit of serialized data emitted from the plugin. It
  * will be imported on client-side and passed as props, context, etc.
  *
- * If it's a string, it's a file path that Webpack can `require`; if it's
+ * If it's a string, it's a file path that the bundler can `require`; if it's
  * an object, it can also contain `query` or other metadata.
  */
 export type Module =
@@ -36,14 +36,45 @@ export type RouteModules = {
   [propName: string]: Module | RouteModules | RouteModules[];
 };
 
+/**
+ * Plugin authors can assign extra metadata to the created routes
+ * It is only available on the Node.js side, and not sent to the browser
+ * Optional: plugin authors are encouraged but not required to provide it
+ *
+ * Some plugins might use this data to provide additional features.
+ * This is the case of the sitemap plugin to provide support for "lastmod".
+ * See also: https://github.com/facebook/docusaurus/pull/9954
+ */
+export type RouteMetadata = {
+  /**
+   * The source code file path that led to the creation of the current route
+   * In official content plugins, this is usually a Markdown or React file
+   * This path is expected to be relative to the site directory
+   */
+  sourceFilePath?: string;
+  /**
+   * The last updated date of this route
+   * This is generally read from the Git history of the sourceFilePath
+   * but can also be provided through other means (usually front matter)
+   *
+   * This has notably been introduced for adding "lastmod" support to the
+   * sitemap plugin, see https://github.com/facebook/docusaurus/pull/9954
+   */
+  lastUpdatedAt?: number;
+};
+
 /**
  * Represents a "slice" of the final route structure returned from the plugin
  * `addRoute` action.
  */
 export type RouteConfig = {
-  /** With leading slash. Trailing slash will be normalized by config. */
+  /**
+   * With leading slash. Trailing slash will be normalized by config.
+   */
   path: string;
-  /** Component used to render this route, a path that Webpack can `require`. */
+  /**
+   * Component used to render this route, a path that the bundler can `require`.
+   */
   component: string;
   /**
    * Props. Each entry should be `[propName]: pathToPropModule` (created with
@@ -56,13 +87,31 @@ export type RouteConfig = {
    * here will be namespaced under {@link RouteContext.data}.
    */
   context?: RouteModules;
-  /** Nested routes config. */
+  /**
+   * Nested routes config, useful for "layout routes" having subroutes.
+   */
   routes?: RouteConfig[];
-  /** React router config option: `exact` routes would not match subroutes. */
+  /**
+   * React router config option: `exact` routes would not match subroutes.
+   */
   exact?: boolean;
-  /** Used to sort routes. Higher-priority routes will be placed first. */
+  /**
+   * React router config option: `strict` routes are sensitive to the presence
+   * of a trailing slash.
+   */
+  strict?: boolean;
+  /**
+   * Used to sort routes.
+   * Higher-priority routes will be matched first.
+   */
   priority?: number;
-  /** Extra props; will be copied to routes.js. */
+  /**
+   * Optional route metadata
+   */
+  metadata?: RouteMetadata;
+  /**
+   * Extra props; will be available on the client side.
+   */
   [propName: string]: unknown;
 };
 
@@ -70,7 +119,7 @@ export type RouteContext = {
   /**
    * Plugin-specific context data.
    */
-  data?: object | undefined;
+  data?: {[key: string]: unknown};
 };
 
 /**