refactor(types): JSDoc for docusaurus config fields (#7291)

facebook · May 3, 2022 · 5bed55a · 5bed55a
1 parent fc8b767
commit 5bed55a
Show file tree

Hide file tree

Showing 9 changed files with 304 additions and 82 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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 `<html lang="...">` and in
+   * `<link ... hreflang="...">`
+   */
   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 `<link hrefLang="x-default">` 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<I18nLocaleConfig>};
 };
 
@@ -60,55 +81,253 @@ 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 `<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;
-  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 `<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;
       }
   )[];
-  clientModules: string[];
-  ssrTemplate?: string;
-  staticDirectories: string[];
+  /**
+   * 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;
       }
   )[];
-  titleDelimiter?: string;
+  /**
+   * 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);
   };
 };
@@ -230,7 +449,7 @@ export type LoadContext = {
   outDir: string;
   /**
    * Duplicated from `siteConfig.baseUrl`, but probably worth keeping. We mutate
-   * `siteConfig` to make `baseUrl` there localized  as well, but that's mostly
+   * `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;

diff --git a/packages/docusaurus/src/server/configValidation.ts b/packages/docusaurus/src/server/configValidation.ts
@@ -223,8 +223,8 @@ export const ConfigSchema = Joi.object({
     .items(Joi.string())
     .default(DEFAULT_CONFIG.clientModules),
   tagline: Joi.string().allow('').default(DEFAULT_CONFIG.tagline),
-  titleDelimiter: Joi.string().default('|'),
-  noIndex: Joi.bool().default(false),
+  titleDelimiter: Joi.string().default(DEFAULT_CONFIG.titleDelimiter),
+  noIndex: Joi.bool().default(DEFAULT_CONFIG.noIndex),
   webpack: Joi.object({
     jsLoader: Joi.alternatives()
       .try(Joi.string().equal('babel'), Joi.function())