diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 8cd2de136128..a49bf9c28037 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -27,7 +27,7 @@ jobs:
cache: yarn
- name: Installation
run: yarn
- # run: yarn install --immutable # Fails if yarn.lock is modified (unfortunately only works for Yarn 2, and --frozen-lockfile is not the same!)
+ # run: yarn install --immutable # Fails if yarn.lock is modified (unfortunately only works for Yarn 2, and --frozen-lockfile is not the same!)
- name: Check immutable yarn.lock
run: git diff --exit-code
- name: Lint
diff --git a/package.json b/package.json
index 9a00d425ae23..4a6e670fda09 100644
--- a/package.json
+++ b/package.json
@@ -47,7 +47,7 @@
"format:diff": "prettier --list-different .",
"lint": "yarn lint:js && yarn lint:style && yarn lint:spelling",
"lint:ci": "yarn lint:js --quiet && yarn lint:style && yarn lint:spelling",
- "lint:js": "eslint --cache --report-unused-disable-directives \"**/*.{js,jsx,ts,tsx,mjs}\"",
+ "lint:js": "eslint --cache --report-unused-disable-directives \"**/*.{js,jsx,ts,tsx,mjs}\"",
"lint:spelling": "cspell \"**\" --no-progress",
"lint:style": "stylelint \"**/*.css\"",
"lerna": "lerna",
diff --git a/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx b/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx
index 5724365b5f2b..e6d981234dde 100644
--- a/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx
+++ b/packages/docusaurus-plugin-debug/src/theme/DebugJsonView/index.tsx
@@ -10,7 +10,7 @@ import BrowserOnly from '@docusaurus/BrowserOnly';
import type {Props} from '@theme/DebugJsonView';
import type {ReactJsonViewProps} from 'react-json-view';
-// Avoids "react-json-view" to display "root"
+// Avoids "react-json-view" displaying "root"
const RootName = null;
// Seems ReactJson does not work with SSR
diff --git a/packages/docusaurus-types/src/index.d.ts b/packages/docusaurus-types/src/index.d.ts
index a4c187396207..574794220687 100644
--- a/packages/docusaurus-types/src/index.d.ts
+++ b/packages/docusaurus-types/src/index.d.ts
@@ -43,15 +43,36 @@ export type ThemeConfig = {
};
export type I18nLocaleConfig = {
+ /** The label displayed for this locale in the locales dropdown. */
label: string;
+ /**
+ * BCP 47 language tag to use in `` and in
+ * ``
+ */
htmlLang: string;
- direction: string;
+ /** Used to select the locale's CSS and html meta attribute. */
+ direction: 'ltr' | 'rtl';
+ /**
+ * The [calendar](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar)
+ * used to calculate the date era. Note that it doesn't control the actual
+ * string displayed: `MM/DD/YYYY` and `DD/MM/YYYY` are both gregory. To choose
+ * the format (`DD/MM/YYYY` or `MM/DD/YYYY`), set your locale name to `en-GB`
+ * or `en-US` (`en` means `en-US`).
+ */
calendar: string;
};
export type I18nConfig = {
+ /**
+ * The locale that:
+ * 1. Does not have its name in the base URL
+ * 2. Gets started with `docusaurus start` without `--locale` option
+ * 3. Will be used for the `` tag
+ */
defaultLocale: string;
+ /** List of locales deployed on your site. Must contain `defaultLocale`. */
locales: [string, ...string[]];
+ /** Individual options for each locale. */
localeConfigs: {[locale: string]: Partial};
};
@@ -60,36 +81,188 @@ export type I18nConfig = {
*/
export type DocusaurusConfig = {
/**
- * Always has both leading and trailing slash (`/base/`). May be localized.
+ * Title for your website. Will be used in metadata and as browser tab title.
+ *
+ * @see https://docusaurus.io/docs/api/docusaurus-config#title
*/
- baseUrl: string;
- baseUrlIssueBanner: boolean;
- favicon?: string;
- tagline: string;
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;
/**
- * `undefined` = legacy retrocompatible behavior. Usually it means `/file` =>
- * `/file/index.html`.
+ * 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 `` 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;
- noIndex: boolean;
+ /**
+ * 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[];
- themeConfig: ThemeConfig;
+ /**
+ * 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 `