From 4f97c7b52c5621af201a62912848b73ddcdf4b7a Mon Sep 17 00:00:00 2001 From: James <5511220+Zamiell@users.noreply.github.com> Date: Thu, 26 May 2022 03:06:36 -0400 Subject: [PATCH] docs: link every reference of types in API table to the type definition (#7497) * dogfood fix * feat: links for plugin types * better syntax * little refactor * use code title * complete the rest Co-authored-by: Joshua Chen --- .../api/plugins/plugin-client-redirects.md | 12 ++++- .../docs/api/plugins/plugin-content-blog.md | 24 +++++++--- .../docs/api/plugins/plugin-content-docs.md | 48 +++++++++++++------ 3 files changed, 61 insertions(+), 23 deletions(-) diff --git a/website/docs/api/plugins/plugin-client-redirects.md b/website/docs/api/plugins/plugin-client-redirects.md index 3b881f58810a..991ea778ad91 100644 --- a/website/docs/api/plugins/plugin-client-redirects.md +++ b/website/docs/api/plugins/plugin-client-redirects.md @@ -41,17 +41,25 @@ Accepted fields: | --- | --- | --- | --- | | `fromExtensions` | `string[]` | `[]` | The extensions to be removed from the route after redirecting. | | `toExtensions` | `string[]` | `[]` | The extensions to be appended to the route after redirecting. | -| `redirects` | `RedirectRule[]` | `[]` | The list of redirect rules. | -| `createRedirects` | `CreateRedirectsFn` | `undefined` | A callback to create a redirect rule. | +| `redirects` | RedirectRule[] | `[]` | The list of redirect rules. | +| `createRedirects` | CreateRedirectsFn | `undefined` | A callback to create a redirect rule. | +### Types {#types} + +#### `RedirectRule` {#RedirectRule} + ```ts type RedirectRule = { to: string; from: string | string[]; }; +``` +#### `CreateRedirectsFn` {#CreateRedirectsFn} + +```ts type CreateRedirectsFn = (path: string) => string[] | string | null | undefined; ``` diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md index 27db9055ecc6..8cdc51d7c668 100644 --- a/website/docs/api/plugins/plugin-content-blog.md +++ b/website/docs/api/plugins/plugin-content-blog.md @@ -38,7 +38,7 @@ Accepted fields: | Name | Type | Default | Description | | --- | --- | --- | --- | | `path` | `string` | `'blog'` | Path to the blog content directory on the file system, relative to site dir. | -| `editUrl` | string \| EditUrlFunction | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativePostPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | +| `editUrl` | string \| EditUrlFn | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativePostPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | | `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. | | `blogTitle` | `string` | `'Blog'` | Blog page title for better SEO. | | `blogDescription` | `string` | `'Blog'` | Blog page meta description for better SEO. | @@ -61,10 +61,10 @@ Accepted fields: | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. | | `truncateMarker` | `RegExp` | `//` | Truncate marker marking where the summary ends. | | `showReadingTime` | `boolean` | `true` | Show estimated reading time for the blog post. | -| `readingTime` | `ReadingTimeFunctionOption` | The default reading time | A callback to customize the reading time number displayed. | +| `readingTime` | `ReadingTimeFn` | The default reading time | A callback to customize the reading time number displayed. | | `authorsMapPath` | `string` | `'authors.yml'` | Path to the authors map file, relative to the blog content directory. | | `feedOptions` | _See below_ | `{type: ['rss', 'atom']}` | Blog feed. | -| `feedOptions.type` | FeedType \| FeedType[] \| 'all' \| null | **Required** | Type of feed to be generated. Use `null` to disable generation. | +| `feedOptions.type` | FeedType \| FeedType[] \| 'all' \| null | **Required** | Type of feed to be generated. Use `null` to disable generation. | | `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. | | `feedOptions.description` | `string` | \`${siteConfig.title} Blog\` | Description of the feed. | | `feedOptions.copyright` | `string` | `undefined` | Copyright message. | @@ -73,6 +73,10 @@ Accepted fields: +### Types {#types} + +#### `EditUrlFn` {#EditUrlFn} + ```ts type EditUrlFunction = (params: { blogDirPath: string; @@ -80,24 +84,32 @@ type EditUrlFunction = (params: { permalink: string; locale: string; }) => string | undefined; +``` + +#### `ReadingTimeFn` {#ReadingTimeFn} +```ts type ReadingTimeOptions = { wordsPerMinute: number; wordBound: (char: string) => boolean; }; -type ReadingTimeFunction = (params: { +type ReadingTimeCalculator = (params: { content: string; frontMatter?: BlogPostFrontMatter & Record; options?: ReadingTimeOptions; }) => number; -type ReadingTimeFunctionOption = (params: { +type ReadingTimeFn = (params: { content: string; frontMatter: BlogPostFrontMatter & Record; - defaultReadingTime: ReadingTimeFunction; + defaultReadingTime: ReadingTimeCalculator; }) => number | undefined; +``` +#### `FeedType` {#FeedType} + +```ts type FeedType = 'rss' | 'atom' | 'json'; ``` diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 331c7cb0a9f9..a44ce3ca1a5a 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -32,7 +32,7 @@ Accepted fields: | Name | Type | Default | Description | | --- | --- | --- | --- | | `path` | `string` | `'docs'` | Path to the docs content directory on the file system, relative to site directory. | -| `editUrl` | string \| EditUrlFunction | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | +| `editUrl` | string \| EditUrlFunction | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | | `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. | | `editCurrentVersion` | `boolean` | `false` | The edit URL will always target the current version doc instead of older versions. Ignored when `editUrl` is a function. | | `routeBasePath` | `string` | `'docs'` | URL route for the docs section of your site. **DO NOT** include a trailing slash. Use `/` for shipping docs without base path. | @@ -42,8 +42,8 @@ Accepted fields: | `sidebarPath` | false \| string | `undefined` | Path to sidebar configuration. Use `false` to disable sidebars, or `undefined` to create a fully autogenerated sidebar. | | `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. See also [Collapsible categories](/docs/sidebar#collapsible-categories) | | `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. See also [Expanded categories by default](/docs/sidebar#expanded-categories-by-default) | -| `sidebarItemsGenerator` | `SidebarGenerator` | _Omitted_ | Function used to replace the sidebar items of type `'autogenerated'` with real sidebar items (docs, categories, links...). See also [Customize the sidebar items generator](/docs/sidebar#customize-the-sidebar-items-generator) | -| `numberPrefixParser` | boolean \| PrefixParser | _Omitted_ | Custom parsing logic to extract number prefixes from file names. Use `false` to disable this behavior and leave the docs untouched, and `true` to use the default parser. See also [Using number prefixes](/docs/sidebar#using-number-prefixes) | +| `sidebarItemsGenerator` | SidebarGenerator | _Omitted_ | Function used to replace the sidebar items of type `'autogenerated'` with real sidebar items (docs, categories, links...). See also [Customize the sidebar items generator](/docs/sidebar#customize-the-sidebar-items-generator) | +| `numberPrefixParser` | boolean \| PrefixParser | _Omitted_ | Custom parsing logic to extract number prefixes from file names. Use `false` to disable this behavior and leave the docs untouched, and `true` to use the default parser. See also [Using number prefixes](/docs/sidebar#using-number-prefixes) | | `docLayoutComponent` | `string` | `'@theme/DocPage'` | Root layout component of each doc page. Provides the version data context, and is not unmounted when switching docs. | | `docItemComponent` | `string` | `'@theme/DocItem'` | Main doc container, with TOC, pagination, etc. | | `docTagsListComponent` | `string` | `'@theme/DocTagsListPage'` | Root component of the tags list page | @@ -60,10 +60,14 @@ Accepted fields: | `includeCurrentVersion` | `boolean` | `true` | Include the current version of your docs. | | `lastVersion` | `string` | First version in `versions.json` | The version navigated to in priority and displayed by default for docs navbar items. | | `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. | -| `versions` | `VersionsConfig` | `{}` | Independent customization of each version's properties. | +| `versions` | VersionsConfig | `{}` | Independent customization of each version's properties. | +### Types {#types} + +#### `EditUrlFunction` {#EditUrlFunction} + ```ts type EditUrlFunction = (params: { version: string; @@ -72,24 +76,20 @@ type EditUrlFunction = (params: { permalink: string; locale: string; }) => string | undefined; +``` +#### `PrefixParser` {#PrefixParser} + +```ts type PrefixParser = (filename: string) => { filename: string; numberPrefix?: number; }; +``` -type CategoryIndexMatcher = (param: { - /** The file name, without extension */ - fileName: string; - /** - * The list of directories, from lowest level to highest. - * If there's no dir name, directories is ['.'] - */ - directories: string[]; - /** The extension, with a leading dot */ - extension: string; -}) => boolean; +#### `SidebarGenerator` {#SidebarGenerator} +```ts type SidebarGenerator = (generatorArgs: { /** The sidebar item with type "autogenerated" to be transformed. */ item: {type: 'autogenerated'; dirName: string}; @@ -118,8 +118,26 @@ type SidebarGenerator = (generatorArgs: { * Docusaurus. */ defaultSidebarItemsGenerator: SidebarGenerator; + // Returns an array of sidebar items — same as what you can declare in + // sidebars.js, except for shorthands. See https://docusaurus.io/docs/sidebar/items }) => Promise; +type CategoryIndexMatcher = (param: { + /** The file name, without extension */ + fileName: string; + /** + * The list of directories, from lowest level to highest. + * If there's no dir name, directories is ['.'] + */ + directories: string[]; + /** The extension, with a leading dot */ + extension: string; +}) => boolean; +``` + +#### `VersionsConfig` {#VersionsConfig} + +```ts type VersionsConfig = { [versionName: string]: { /**