mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-02 16:29:47 +02:00
refactor(types): JSDoc for docusaurus config fields (#7291)
This commit is contained in:
Joshua Chen
GitHub
parent
fc8b7674e3
commit
5bed55aeda
9 changed files with 308 additions and 86 deletions
257
packages/docusaurus-types/src/index.d.ts
vendored
257
packages/docusaurus-types/src/index.d.ts
vendored
|
|
@ -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,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;
|
||||
onBrokenLinks: ReportingSeverity;
|
||||
onBrokenMarkdownLinks: ReportingSeverity;
|
||||
onDuplicateRoutes: ReportingSeverity;
|
||||
/**
|
||||
* 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;
|
||||
/**
|
||||
* 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;
|
||||
plugins: PluginConfig[];
|
||||
themes: PluginConfig[];
|
||||
presets: PresetConfig[];
|
||||
/**
|
||||
* 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[];
|
||||
/**
|
||||
* 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
|
||||
| {
|
||||
|
|
@ -97,9 +270,14 @@ export type DocusaurusConfig = {
|
|||
[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
|
||||
| {
|
||||
|
|
@ -107,8 +285,49 @@ export type DocusaurusConfig = {
|
|||
[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;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue