refactor(types): split into multiple files (#7710)

packages/docusaurus-types/src/clientModule.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {Location} from 'history';
+
+export type ClientModule = {
+  onRouteDidUpdate?: (args: {
+    previousLocation: Location | null;
+    location: Location;
+  }) => (() => void) | void;
+  onRouteUpdate?: (args: {
+    previousLocation: Location | null;
+    location: Location;
+  }) => (() => void) | void;
+};

packages/docusaurus-types/src/config.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {RuleSetRule} from 'webpack';
+import type {Required as RequireKeys, DeepPartial} from 'utility-types';
+import type {I18nConfig} from './i18n';
+import type {PluginConfig, PresetConfig} from './plugin';
+
+export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';
+
+export type ThemeConfig = {
+  [key: string]: unknown;
+};
+
+/**
+ * Docusaurus config, after validation/normalization.
+ */
+export type DocusaurusConfig = {
+  /**
+   * Title for your website. Will be used in metadata and as browser tab title.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#title
+   */
+  title: string;
+  /**
+   * URL for your website. This can also be considered the top-level hostname.
+   * For example, `https://facebook.github.io` is the URL of
+   * https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL
+   * for https://docusaurus.io.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#url
+   */
+  url: string;
+  /**
+   * Can be considered as the path after the host. For example, `/metro/` is the
+   * base URL of https://facebook.github.io/metro/. For URLs that have no path,
+   * it should be set to `/`. Always has both leading and trailing slash.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#baseUrl
+   */
+  baseUrl: string;
+  /**
+   * Path to your site favicon; must be a URL that can be used in link's href.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#favicon
+   */
+  favicon?: string;
+  /**
+   * Allow to customize the presence/absence of a trailing slash at the end of
+   * URLs/links, and how static HTML files are generated:
+   *
+   * - `undefined` (default): keeps URLs untouched, and emit
+   *   `/docs/myDoc/index.html` for `/docs/myDoc.md`
+   * - `true`: add trailing slashes to URLs/links, and emit
+   *   `/docs/myDoc/index.html` for `/docs/myDoc.md`
+   * - `false`: remove trailing slashes from URLs/links, and emit
+   *   `/docs/myDoc.html` for `/docs/myDoc.md`
+   *
+   * @see https://github.com/slorber/trailing-slash-guide
+   * @see https://docusaurus.io/docs/api/docusaurus-config#trailingSlash
+   * @default undefined
+   */
+  trailingSlash: boolean | undefined;
+  /**
+   * The i18n configuration object to [localize your
+   * site](https://docusaurus.io/docs/i18n/introduction).
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#i18n
+   */
+  i18n: I18nConfig;
+  /**
+   * This option adds `<meta name="robots" content="noindex, nofollow">` to
+   * every page to tell search engines to avoid indexing your site.
+   *
+   * @see https://moz.com/learn/seo/robots-meta-directives
+   * @see https://docusaurus.io/docs/api/docusaurus-config#noIndex
+   * @default false
+   */
+  noIndex: boolean;
+  /**
+   * The behavior of Docusaurus when it detects any broken link.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#onBrokenLinks
+   * @default "throw"
+   */
+  onBrokenLinks: ReportingSeverity;
+  /**
+   * The behavior of Docusaurus when it detects any broken markdown link.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#onBrokenMarkdownLinks
+   * @default "warn"
+   */
+  onBrokenMarkdownLinks: ReportingSeverity;
+  /**
+   * The behavior of Docusaurus when it detects any [duplicate
+   * routes](https://docusaurus.io/docs/creating-pages#duplicate-routes).
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#onDuplicateRoutes
+   * @default "warn"
+   */
+  onDuplicateRoutes: ReportingSeverity;
+  /**
+   * The tagline for your website.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#tagline
+   * @default ""
+   */
+  tagline: string;
+  /**
+   * The GitHub user or organization that owns the repository. You don't need
+   * this if you are not using the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#organizationName
+   */
+  organizationName?: string;
+  /**
+   * The name of the GitHub repository. You don't need this if you are not using
+   * the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#projectName
+   */
+  projectName?: string;
+  /**
+   * The name of the branch to deploy the static files to. You don't need this
+   * if you are not using the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#deploymentBranch
+   */
+  deploymentBranch?: string;
+  /**
+   * The hostname of your server. Useful if you are using GitHub Enterprise. You
+   * don't need this if you are not using the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#githubHost
+   */
+  githubHost?: string;
+  /**
+   * The port of your server. Useful if you are using GitHub Enterprise. You
+   * don't need this if you are not using the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#githubPort
+   */
+  githubPort?: string;
+  /**
+   * The [theme configuration](https://docusaurus.io/docs/api/themes/configuration)
+   * object to customize your site UI like navbar and footer.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#themeConfig
+   * @default {}
+   */
+  themeConfig: ThemeConfig;
+  /**
+   * List of plugins.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#plugins
+   * @default []
+   */
+  plugins: PluginConfig[];
+  /**
+   * List of themes.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#themes
+   * @default []
+   */
+  themes: PluginConfig[];
+  /**
+   * List of presets.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#presets
+   * @default []
+   */
+  presets: PresetConfig[];
+  /**
+   * Docusaurus guards `docusaurus.config.js` from unknown fields. To add a
+   * custom field, define it on `customFields`.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#customFields
+   * @default {}
+   */
+  customFields?: {
+    [key: string]: unknown;
+  };
+  /**
+   * An array of paths, relative to the site's directory or absolute. Files
+   * under these paths will be copied to the build output as-is.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#staticDirectories
+   * @default ["static"]
+   */
+  staticDirectories: string[];
+  /**
+   * An array of scripts to load. The values can be either strings or plain
+   * objects of attribute-value maps. The `<script>` tags will be inserted in
+   * the HTML `<head>`.
+   *
+   * Note that `<script>` added here are render-blocking, so you might want to
+   * add `async: true`/`defer: true` to the objects.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#scripts
+   * @default []
+   */
+  scripts: (
+    | string
+    | {
+        src: string;
+        [key: string]: string | boolean | undefined;
+      }
+  )[];
+  /**
+   * An array of CSS sources to load. The values can be either strings or plain
+   * objects of attribute-value maps. The `<link>` tags will be inserted in the
+   * HTML `<head>`.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#stylesheets
+   * @default []
+   */
+  stylesheets: (
+    | string
+    | {
+        href: string;
+        [key: string]: string | boolean | undefined;
+      }
+  )[];
+  /**
+   * An array of [client modules](https://docusaurus.io/docs/advanced/client#client-modules)
+   * to load globally on your site.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#clientModules
+   * @default []
+   */
+  clientModules: string[];
+  /**
+   * An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview)
+   * that will be used to render your application. This can be used to set
+   * custom attributes on the `body` tags, additional `meta` tags, customize the
+   * `viewport`, etc. Please note that Docusaurus will rely on the template to
+   * be correctly structured in order to function properly, once you do
+   * customize it, you will have to make sure that your template is compliant
+   * with the requirements from upstream.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#ssrTemplate
+   */
+  ssrTemplate?: string;
+  /**
+   * Will be used as title delimiter in the generated `<title>` tag.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#titleDelimiter
+   * @default "|"
+   */
+  titleDelimiter: string;
+  /**
+   * When enabled, will show a banner in case your site can't load its CSS or
+   * JavaScript files, which is a very common issue, often related to a wrong
+   * `baseUrl` in site config.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#baseUrlIssueBanner
+   * @default true
+   */
+  baseUrlIssueBanner: boolean;
+  /** Webpack-related options. */
+  webpack?: {
+    /**
+     * Configuration for alternative JS loaders. "babel" will use the built-in
+     * Babel loader and preset; otherwise, you can provide your custom Webpack
+     * rule set.
+     */
+    jsLoader: 'babel' | ((isServer: boolean) => RuleSetRule);
+  };
+};
+
+/**
+ * Docusaurus config, as provided by the user (partial/unnormalized). This type
+ * is used to provide type-safety / IDE auto-complete on the config file.
+ * @see https://docusaurus.io/docs/typescript-support
+ */
+export type Config = RequireKeys<
+  DeepPartial<DocusaurusConfig>,
+  'title' | 'url' | 'baseUrl'
+>;

packages/docusaurus-types/src/context.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type {DocusaurusConfig} from './config';
+import type {CodeTranslations, I18n} from './i18n';
+import type {LoadedPlugin, PluginVersionInformation} from './plugin';
+import type {RouteConfig} from './routing';
+
+export type DocusaurusContext = {
+  siteConfig: DocusaurusConfig;
+  siteMetadata: SiteMetadata;
+  globalData: GlobalData;
+  i18n: I18n;
+  codeTranslations: CodeTranslations;
+
+  // Don't put mutable values here, to avoid triggering re-renders
+  // We could reconsider that choice if context selectors are implemented
+  // isBrowser: boolean; // Not here on purpose!
+};
+
+export type SiteMetadata = {
+  readonly docusaurusVersion: string;
+  readonly siteVersion?: string;
+  readonly pluginVersions: {[pluginName: string]: PluginVersionInformation};
+};
+
+export type GlobalData = {[pluginName: string]: {[pluginId: string]: unknown}};
+
+export type LoadContext = {
+  siteDir: string;
+  generatedFilesDir: string;
+  siteConfig: DocusaurusConfig;
+  siteConfigPath: string;
+  outDir: string;
+  /**
+   * Directory where all source translations for the current locale can be found
+   * in. Constructed with `i18n.path` + `i18n.currentLocale.path` (e.g.
+   * `<siteDir>/i18n/en`)
+   */
+  localizationDir: string;
+  /**
+   * Duplicated from `siteConfig.baseUrl`, but probably worth keeping. We mutate
+   * `siteConfig` to make `baseUrl` there localized as well, but that's mostly
+   * for client-side. `context.baseUrl` is still more convenient for plugins.
+   */
+  baseUrl: string;
+  i18n: I18n;
+  codeTranslations: CodeTranslations;
+};
+
+export type Props = LoadContext & {
+  headTags: string;
+  preBodyTags: string;
+  postBodyTags: string;
+  siteMetadata: SiteMetadata;
+  routes: RouteConfig[];
+  routesPaths: string[];
+  plugins: LoadedPlugin[];
+};