@docusaurus/types 3.8.1 → 3.9.0-canary-6406

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/types",
-  "version": "3.8.1",
+  "version": "3.9.0-canary-6406",
   "description": "Common types for Docusaurus packages.",
   "types": "./src/index.d.ts",
   "publishConfig": {
@@ -15,6 +15,7 @@
   "dependencies": {
     "@mdx-js/mdx": "^3.0.0",
     "@types/history": "^4.7.11",
+    "@types/mdast": "^4.0.2",
     "@types/react": "*",
     "commander": "^5.1.0",
     "joi": "^17.9.2",
@@ -27,5 +28,5 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
-  "gitHead": "fa8ae13e668fcbc0481ce10c0a734e2a5b397293"
+  "gitHead": "796441f4f831278ffc57971fabcd4c730da9e9d7"
 }

package/src/config.d.ts

@@ -10,12 +10,8 @@ import type {RuleSetRule} from 'webpack';
 import type {DeepPartial, Overwrite} from 'utility-types';
 import type {I18nConfig} from './i18n';
 import type {PluginConfig, PresetConfig, HtmlTagObject} from './plugin';
-
-import type {ProcessorOptions} from '@mdx-js/mdx';
-
-export type RemarkRehypeOptions = ProcessorOptions['remarkRehypeOptions'];
-
-export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';
+import type {ReportingSeverity} from './reporting';
+import type {MarkdownConfig} from './markdown';
 
 export type RouterType = 'browser' | 'hash';
 
@@ -23,101 +19,6 @@ export type ThemeConfig = {
   [key: string]: unknown;
 };
 
-export type MarkdownPreprocessor = (args: {
-  filePath: string;
-  fileContent: string;
-}) => string;
-
-export type MDX1CompatOptions = {
-  comments: boolean;
-  admonitions: boolean;
-  headingIds: boolean;
-};
-
-export type ParseFrontMatterParams = {filePath: string; fileContent: string};
-export type ParseFrontMatterResult = {
-  frontMatter: {[key: string]: unknown};
-  content: string;
-};
-export type DefaultParseFrontMatter = (
-  params: ParseFrontMatterParams,
-) => Promise<ParseFrontMatterResult>;
-export type ParseFrontMatter = (
-  params: ParseFrontMatterParams & {
-    defaultParseFrontMatter: DefaultParseFrontMatter;
-  },
-) => Promise<ParseFrontMatterResult>;
-
-export type MarkdownAnchorsConfig = {
-  /**
-   * Preserves the case of the heading text when generating anchor ids.
-   */
-  maintainCase: boolean;
-};
-
-export type MarkdownConfig = {
-  /**
-   * The Markdown format to use by default.
-   *
-   * This is the format passed down to the MDX compiler, impacting the way the
-   * content is parsed.
-   *
-   * Possible values:
-   * - `'mdx'`: use the MDX format (JSX support)
-   * - `'md'`: use the CommonMark format (no JSX support)
-   * - `'detect'`: select the format based on file extension (.md / .mdx)
-   *
-   * @see https://mdxjs.com/packages/mdx/#optionsformat
-   * @default 'mdx'
-   */
-  format: 'mdx' | 'md' | 'detect';
-
-  /**
-   * A function callback that lets users parse the front matter themselves.
-   * Gives the opportunity to read it from a different source, or process it.
-   *
-   * @see https://github.com/facebook/docusaurus/issues/5568
-   */
-  parseFrontMatter: ParseFrontMatter;
-
-  /**
-   * Allow mermaid language code blocks to be rendered into Mermaid diagrams:
-   *
-   * - `true`: code blocks with language mermaid will be rendered.
-   * - `false` | `undefined` (default): code blocks with language mermaid
-   * will be left as code blocks.
-   *
-   * @see https://docusaurus.io/docs/markdown-features/diagrams/
-   * @default false
-   */
-  mermaid: boolean;
-
-  /**
-   * Gives opportunity to preprocess the MDX string content before compiling.
-   * A good escape hatch that can be used to handle edge cases.
-   *
-   * @param args
-   */
-  preprocessor?: MarkdownPreprocessor;
-
-  /**
-   * Set of flags make it easier to upgrade from MDX 1 to MDX 2
-   * See also https://github.com/facebook/docusaurus/issues/4029
-   */
-  mdx1Compat: MDX1CompatOptions;
-
-  /**
-   * Ability to provide custom remark-rehype options
-   * See also https://github.com/remarkjs/remark-rehype#options
-   */
-  remarkRehypeOptions: RemarkRehypeOptions;
-
-  /**
-   * Options to control the behavior of anchors generated from Markdown headings
-   */
-  anchors: MarkdownAnchorsConfig;
-};
-
 export type StorageConfig = {
   type: SiteStorage['type'];
   namespace: boolean | string;
@@ -258,7 +159,8 @@ export type DocusaurusConfig = {
    * @see https://docusaurus.io/docs/api/docusaurus-config#onBrokenMarkdownLinks
    * @default "warn"
    */
-  onBrokenMarkdownLinks: ReportingSeverity;
+  // TODO Docusaurus v4 remove
+  onBrokenMarkdownLinks: ReportingSeverity | undefined;
   /**
    * The behavior of Docusaurus when it detects any [duplicate
    * routes](https://docusaurus.io/docs/creating-pages#duplicate-routes).

package/src/i18n.d.ts

@@ -32,6 +32,30 @@ export type I18nLocaleConfig = {
    * name.
    */
   path: string;
+  /**
+   * Should we attempt to translate this locale?
+   * By default, it will only be run if the `./i18n/<locale>` exists.
+   */
+  translate: boolean;
+
+  /**
+   * For i18n sites deployed to distinct domains, it is recommended to configure
+   * a site url on a per-locale basis.
+   */
+  url: string;
+
+  /**
+   * An explicit baseUrl to use for this locale, overriding the default one:
+   * Default values:
+   * - Default locale: `/${siteConfig.baseUrl}/`
+   * - Other locales: `/${siteConfig.baseUrl}/<locale>/`
+   *
+   * Exception: when using the CLI with a single `--locale` parameter, the
+   * `/<locale>/` path segment is not included. This is a better default for
+   * sites looking to deploy each locale to a different subdomain, such as
+   * `https://<locale>.docusaurus.io`
+   */
+  baseUrl: string;
 };
 
 export type I18nConfig = {

package/src/index.d.ts

@@ -6,19 +6,27 @@
  */
 
 export {
-  ReportingSeverity,
   RouterType,
   ThemeConfig,
-  MarkdownConfig,
-  DefaultParseFrontMatter,
-  ParseFrontMatter,
   DocusaurusConfig,
   FutureConfig,
+  FutureV4Config,
   FasterConfig,
   StorageConfig,
   Config,
 } from './config';
 
+export {
+  MarkdownConfig,
+  MarkdownHooks,
+  DefaultParseFrontMatter,
+  ParseFrontMatter,
+  OnBrokenMarkdownLinksFunction,
+  OnBrokenMarkdownImagesFunction,
+} from './markdown';
+
+export {ReportingSeverity} from './reporting';
+
 export {
   SiteMetadata,
   DocusaurusContext,

package/src/markdown.d.ts

@@ -0,0 +1,175 @@
+/**
+ * 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 {ProcessorOptions} from '@mdx-js/mdx';
+import type {Image, Definition, Link} from 'mdast';
+
+import type {ReportingSeverity} from './reporting';
+
+export type RemarkRehypeOptions = ProcessorOptions['remarkRehypeOptions'];
+
+export type MarkdownPreprocessor = (args: {
+  filePath: string;
+  fileContent: string;
+}) => string;
+
+export type MDX1CompatOptions = {
+  comments: boolean;
+  admonitions: boolean;
+  headingIds: boolean;
+};
+
+export type ParseFrontMatterParams = {filePath: string; fileContent: string};
+export type ParseFrontMatterResult = {
+  frontMatter: {[key: string]: unknown};
+  content: string;
+};
+export type DefaultParseFrontMatter = (
+  params: ParseFrontMatterParams,
+) => Promise<ParseFrontMatterResult>;
+export type ParseFrontMatter = (
+  params: ParseFrontMatterParams & {
+    defaultParseFrontMatter: DefaultParseFrontMatter;
+  },
+) => Promise<ParseFrontMatterResult>;
+
+export type MarkdownAnchorsConfig = {
+  /**
+   * Preserves the case of the heading text when generating anchor ids.
+   */
+  maintainCase: boolean;
+};
+
+export type OnBrokenMarkdownLinksFunction = (params: {
+  /**
+   * Path of the source file on which the broken link was found
+   * Relative to the site dir.
+   * Example: "docs/category/myDoc.mdx"
+   */
+  sourceFilePath: string;
+
+  /**
+   * The Markdown link url that couldn't be resolved.
+   * Technically, in this context, it's more a "relative file path", but let's
+   * name it url for consistency with usual Markdown names and the MDX AST
+   * Example: "relative/dir/myTargetDoc.mdx?query#hash"
+   */
+  url: string;
+  /**
+   * The Markdown Link AST node.
+   */
+  node: Link | Definition;
+}) => void | string;
+
+export type OnBrokenMarkdownImagesFunction = (params: {
+  /**
+   * Path of the source file on which the broken image was found
+   * Relative to the site dir.
+   * Example: "docs/category/myDoc.mdx"
+   */
+  sourceFilePath: string;
+
+  /**
+   * The Markdown image url that couldn't be resolved.
+   * Technically, in this context, it's more a "relative file path", but let's
+   * name it url for consistency with usual Markdown names and the MDX AST
+   * Example: "relative/dir/myImage.png"
+   */
+  url: string;
+  /**
+   * The Markdown Image AST node.
+   */
+  node: Image;
+}) => void | string;
+
+export type MarkdownHooks = {
+  /**
+   * The behavior of Docusaurus when it detects any broken Markdown link.
+   *
+   * // TODO refactor doc links!
+   * @see https://docusaurus.io/docs/api/docusaurus-config#onBrokenMarkdownLinks
+   * @default "warn"
+   */
+  onBrokenMarkdownLinks: ReportingSeverity | OnBrokenMarkdownLinksFunction;
+
+  onBrokenMarkdownImages: ReportingSeverity | OnBrokenMarkdownImagesFunction;
+};
+
+export type MarkdownConfig = {
+  /**
+   * The Markdown format to use by default.
+   *
+   * This is the format passed down to the MDX compiler, impacting the way the
+   * content is parsed.
+   *
+   * Possible values:
+   * - `'mdx'`: use the MDX format (JSX support)
+   * - `'md'`: use the CommonMark format (no JSX support)
+   * - `'detect'`: select the format based on file extension (.md / .mdx)
+   *
+   * @see https://mdxjs.com/packages/mdx/#optionsformat
+   * @default 'mdx'
+   */
+  format: 'mdx' | 'md' | 'detect';
+
+  /**
+   * A function callback that lets users parse the front matter themselves.
+   * Gives the opportunity to read it from a different source, or process it.
+   *
+   * @see https://github.com/facebook/docusaurus/issues/5568
+   */
+  parseFrontMatter: ParseFrontMatter;
+
+  /**
+   * Allow mermaid language code blocks to be rendered into Mermaid diagrams:
+   *
+   * - `true`: code blocks with language mermaid will be rendered.
+   * - `false` | `undefined` (default): code blocks with language mermaid
+   * will be left as code blocks.
+   *
+   * @see https://docusaurus.io/docs/markdown-features/diagrams/
+   * @default false
+   */
+  mermaid: boolean;
+
+  /**
+   * Allow remark-emoji to convert emoji shortcodes to Unicode emoji.
+   * - `true` (default): enables the remark-emoji plugin to convert shortcodes
+   * - `false`: disables the remark-emoji plugin
+   *
+   * @see https://github.com/rhysd/remark-emoji
+   * @default true
+   */
+  emoji: boolean;
+
+  /**
+   * Gives opportunity to preprocess the MDX string content before compiling.
+   * A good escape hatch that can be used to handle edge cases.
+   *
+   * @param args
+   */
+  preprocessor?: MarkdownPreprocessor;
+
+  /**
+   * Set of flags make it easier to upgrade from MDX 1 to MDX 2
+   * See also https://github.com/facebook/docusaurus/issues/4029
+   */
+  mdx1Compat: MDX1CompatOptions;
+
+  /**
+   * Ability to provide custom remark-rehype options
+   * See also https://github.com/remarkjs/remark-rehype#options
+   */
+  remarkRehypeOptions: RemarkRehypeOptions;
+
+  /**
+   * Options to control the behavior of anchors generated from Markdown headings
+   */
+  anchors: MarkdownAnchorsConfig;
+
+  hooks: MarkdownHooks;
+};

package/src/reporting.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';