@docusaurus/types - npm Package Compare versions

Comparing version 3.8.1 to 3.9.0-canary-6403

src/markdown.d.ts

+/**
+ * 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;
+};

src/reporting.d.ts

+/**
+ * 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';

package.json

 {
   "name": "@docusaurus/types",
-  "version": "3.8.1",
+  "version": "3.9.0-canary-6403",
   "description": "Common types for Docusaurus packages.",
@@ -18,2 +18,3 @@ "types": "./src/index.d.ts",
     "@types/history": "^4.7.11",
+    "@types/mdast": "^4.0.2",
     "@types/react": "*",
@@ -31,3 +32,3 @@ "commander": "^5.1.0",
   },
-  "gitHead": "fa8ae13e668fcbc0481ce10c0a734e2a5b397293"
+  "gitHead": "22c95f8cb5c070ce47e115be376fa9b828dd54df"
 }

src/config.d.ts

@@ -13,9 +13,5 @@ /**
 import type {PluginConfig, PresetConfig, HtmlTagObject} from './plugin';
+import type {ReportingSeverity} from './reporting';
+import type {MarkdownConfig} from './markdown';
 
-import type {ProcessorOptions} from '@mdx-js/mdx';
-
-export type RemarkRehypeOptions = ProcessorOptions['remarkRehypeOptions'];
-
-export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';
-
 export type RouterType = 'browser' | 'hash';
@@ -27,97 +23,2 @@
 
-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 = {
@@ -263,3 +164,4 @@ type: SiteStorage['type'];
    */
-  onBrokenMarkdownLinks: ReportingSeverity;
+  // TODO Docusaurus v4 remove
+  onBrokenMarkdownLinks: ReportingSeverity | undefined;
   /**
@@ -266,0 +168,0 @@ * The behavior of Docusaurus when it detects any [duplicate

src/i18n.d.ts

@@ -35,2 +35,26 @@ /**
   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;
 };
@@ -37,0 +61,0 @@

src/index.d.ts

@@ -9,10 +9,7 @@ /**
 export {
-  ReportingSeverity,
   RouterType,
   ThemeConfig,
-  MarkdownConfig,
-  DefaultParseFrontMatter,
-  ParseFrontMatter,
   DocusaurusConfig,
   FutureConfig,
+  FutureV4Config,
   FasterConfig,
@@ -24,2 +21,13 @@ StorageConfig,
 export {
+  MarkdownConfig,
+  MarkdownHooks,
+  DefaultParseFrontMatter,
+  ParseFrontMatter,
+  OnBrokenMarkdownLinksFunction,
+  OnBrokenMarkdownImagesFunction,
+} from './markdown';
+
+export {ReportingSeverity} from './reporting';
+
+export {
   SiteMetadata,
@@ -26,0 +34,0 @@ DocusaurusContext,

New alerts

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Fixed alerts

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

44396

8.77%

Number of package files

15

15.38%

Lines of code

1273

8.9%

Worsened metrics

Dependency count

12

9.09%

Number of low quality alerts

2

100%

Number of low supply chain risk alerts

6

20%

Dependency changes

• + Added

  @types/mdast@^4.0.2