From 5bed55aeda6446c15a617cf8d9f05adcee532c98 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Tue, 3 May 2022 13:57:19 +0800 Subject: [PATCH] refactor(types): JSDoc for docusaurus config fields (#7291) --- .github/workflows/lint.yml | 2 +- package.json | 2 +- .../src/theme/DebugJsonView/index.tsx | 2 +- packages/docusaurus-types/src/index.d.ts | 249 ++++++++++++++++-- .../docusaurus/src/server/configValidation.ts | 4 +- website/docs/api/docusaurus.config.js.md | 117 ++++---- website/docs/api/plugins/plugin-sitemap.md | 4 +- website/docs/deployment.mdx | 4 +- .../markdown-features-links.md | 2 +- 9 files changed, 304 insertions(+), 82 deletions(-) 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 `