docs: link every reference of types in API table to the type definiti…

…on (#7497) * dogfood fix * feat: links for plugin types * better syntax * little refactor * use code title * complete the rest Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
facebook · May 26, 2022 · 4f97c7b · 4f97c7b
1 parent f947015
commit 4f97c7b
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 23 deletions.
diff --git 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` | <code><a href="#RedirectRule">RedirectRule</a>[]</code> | `[]` | The list of redirect rules. |
+| `createRedirects` | <code><a href="#CreateRedirectsFn">CreateRedirectsFn</a></code> | `undefined` | A callback to create a redirect rule. |
 
 </APITable>
 
+### 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
@@ -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` | <code>string \| EditUrlFunction</code> | `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` | <code>string \| <a href="#EditUrlFn">EditUrlFn</a></code> | `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` | `/<!--\s*(truncate)\s*-->/` | 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` | <code>FeedType \| FeedType[] \| 'all' \| null</code> | **Required** | Type of feed to be generated. Use `null` to disable generation. |
+| `feedOptions.type` | <code><a href="#FeedType">FeedType</a> \| <a href="#FeedType">FeedType</a>[] \| 'all' \| null</code> | **Required** | Type of feed to be generated. Use `null` to disable generation. |
 | `feedOptions.title` | `string` | `siteConfig.title` | Title of the feed. |
 | `feedOptions.description` | `string` | <code>\`${siteConfig.title} Blog\`</code> | Description of the feed. |
 | `feedOptions.copyright` | `string` | `undefined` | Copyright message. |
@@ -73,31 +73,43 @@ Accepted fields:
 
 </APITable>
 
+### Types {#types}
+
+#### `EditUrlFn` {#EditUrlFn}
+
 ```ts
 type EditUrlFunction = (params: {
   blogDirPath: string;
   blogPath: string;
   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<string, unknown>;
   options?: ReadingTimeOptions;
 }) => number;
 
-type ReadingTimeFunctionOption = (params: {
+type ReadingTimeFn = (params: {
   content: string;
   frontMatter: BlogPostFrontMatter & Record<string, unknown>;
-  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
@@ -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` | <code>string \| EditUrlFunction</code> | `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` | <code>string \| <a href="#EditUrlFunction">EditUrlFunction</a></code> | `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` | <code>false \| string</code> | `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` | <code>boolean \| PrefixParser</code> | _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` | <a href="#SidebarGenerator"><code>SidebarGenerator</code></a> | _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` | <code>boolean \|</code> <a href="#PrefixParser"><code>PrefixParser</code></a> | _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` | <a href="#VersionsConfig"><code>VersionsConfig</code></a> | `{}` | Independent customization of each version's properties. |
 
 </APITable>
 
+### 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<SidebarItem[]>;
 
+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]: {
     /**