Heading
; +export default function MyHeading(props) { + useBrokenLinks().collectAnchor(props.id); + return ; } ``` ```js title="MyLink.js" import useBrokenLinks from '@docusaurus/useBrokenLinks'; -export default function MyLink({targetLink, ...props}): JSX.Element { - const brokenLinks = useBrokenLinks(); - - brokenLinks.collectLink(targetLink); - - return Link; +export default function MyLink(props) { + useBrokenLinks().collectLink(props.href); + return ; } ``` diff --git a/website/docs/guides/docs/sidebar/items.mdx b/website/docs/guides/docs/sidebar/items.mdx index 8b2ac4e764e2..1dd0c0100e78 100644 --- a/website/docs/guides/docs/sidebar/items.mdx +++ b/website/docs/guides/docs/sidebar/items.mdx @@ -61,11 +61,11 @@ export default { }; ``` -If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` Markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page. +If you use the doc shorthand or [autogenerated](autogenerated.mdx) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` Markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page. :::note -A `doc` item sets an [implicit sidebar association](#sidebar-association). Don't assign the same doc to multiple sidebars: change the type to `ref` instead. +A `doc` item sets an [implicit sidebar association](./multiple-sidebars.mdx#sidebar-association). Don't assign the same doc to multiple sidebars: change the type to `ref` instead. ::: diff --git a/website/docs/migration/v2/migration-automated.mdx b/website/docs/migration/v2/migration-automated.mdx index 61e07cc4c1f5..ff4139d2e71d 100644 --- a/website/docs/migration/v2/migration-automated.mdx +++ b/website/docs/migration/v2/migration-automated.mdx @@ -24,7 +24,7 @@ The migration CLI migrates: To use the migration CLI, follow these steps: -1. Before using the migration CLI, ensure that `/docs`, `/blog`, `/static`, `sidebars.json`, `siteConfig.js`, `package.json` follow the [structure](#) shown at the start of this page. +1. Before using the migration CLI, ensure that `/docs`, `/blog`, `/static`, `sidebars.json`, `siteConfig.js`, `package.json` follow the expected structure. 2. To migrate your v1 website, run the migration CLI with the appropriate filesystem paths: diff --git a/website/package.json b/website/package.json index 5a6535804c1d..b0e7f456000d 100644 --- a/website/package.json +++ b/website/package.json @@ -1,6 +1,6 @@ { "name": "website", - "version": "3.1.0", + "version": "3.1.1", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -36,19 +36,19 @@ "dependencies": { "@crowdin/cli": "^3.13.0", "@crowdin/crowdin-api-client": "^1.23.3", - "@docusaurus/core": "3.1.0", - "@docusaurus/logger": "3.1.0", - "@docusaurus/plugin-client-redirects": "3.1.0", - "@docusaurus/plugin-ideal-image": "3.1.0", - "@docusaurus/plugin-pwa": "3.1.0", - "@docusaurus/preset-classic": "3.1.0", - "@docusaurus/remark-plugin-npm2yarn": "3.1.0", - "@docusaurus/theme-classic": "3.1.0", - "@docusaurus/theme-common": "3.1.0", - "@docusaurus/theme-live-codeblock": "3.1.0", - "@docusaurus/theme-mermaid": "3.1.0", - "@docusaurus/utils": "3.1.0", - "@docusaurus/utils-common": "3.1.0", + "@docusaurus/core": "3.1.1", + "@docusaurus/logger": "3.1.1", + "@docusaurus/plugin-client-redirects": "3.1.1", + "@docusaurus/plugin-ideal-image": "3.1.1", + "@docusaurus/plugin-pwa": "3.1.1", + "@docusaurus/preset-classic": "3.1.1", + "@docusaurus/remark-plugin-npm2yarn": "3.1.1", + "@docusaurus/theme-classic": "3.1.1", + "@docusaurus/theme-common": "3.1.1", + "@docusaurus/theme-live-codeblock": "3.1.1", + "@docusaurus/theme-mermaid": "3.1.1", + "@docusaurus/utils": "3.1.1", + "@docusaurus/utils-common": "3.1.1", "@popperjs/core": "^2.11.8", "@swc/core": "1.2.197", "clsx": "^2.0.0", @@ -83,8 +83,8 @@ ] }, "devDependencies": { - "@docusaurus/eslint-plugin": "3.1.0", - "@docusaurus/tsconfig": "3.1.0", + "@docusaurus/eslint-plugin": "3.1.1", + "@docusaurus/tsconfig": "3.1.1", "@types/color": "^3.0.4", "@types/jest": "^29.5.3", "cross-env": "^7.0.3", diff --git a/website/src/components/APITable/index.tsx b/website/src/components/APITable/index.tsx index 049e2d4bcfd4..29e9890bea46 100644 --- a/website/src/components/APITable/index.tsx +++ b/website/src/components/APITable/index.tsx @@ -13,6 +13,7 @@ import React, { useRef, useEffect, } from 'react'; +import useBrokenLinks from '@docusaurus/useBrokenLinks'; import {useHistory} from '@docusaurus/router'; import styles from './styles.module.css'; @@ -41,6 +42,7 @@ function APITableRow( const id = name ? `${name}-${entryName}` : entryName; const anchor = `#${id}`; const history = useHistory(); + useBrokenLinks().collectAnchor(id); return (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. |
+| `blogSidebarCount` | number \| 'ALL' | `5` | Number of blog post elements to show in the blog sidebar. `'ALL'` to show all blog posts; `0` to disable. |
+| `blogSidebarTitle` | `string` | `'Recent posts'` | Title of the blog sidebar. |
+| `routeBasePath` | `string` | `'blog'` | URL route for the blog section of your site. **DO NOT** include a trailing slash. Use `/` to put the blog at root path. |
+| `tagsBasePath` | `string` | `'tags'` | URL route for the tags section of your blog. Will be appended to `routeBasePath`. **DO NOT** include a trailing slash. |
+| `archiveBasePath` | string \| null | `'archive'` | URL route for the archive section of your blog. Will be appended to `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to disable generation of archive. |
+| `include` | `string[]` | `['**/*.{md,mdx}']` | Array of glob patterns matching Markdown files to be built, relative to the content path. |
+| `exclude` | `string[]` | _See example configuration_ | Array of glob patterns matching Markdown files to be excluded. Serves as refinement based on the `include` option. |
+| `postsPerPage` | number \| 'ALL' | `10` | Number of posts to show per page in the listing page. Use `'ALL'` to display all posts on one listing page. |
+| `blogListComponent` | `string` | `'@theme/BlogListPage'` | Root component of the blog listing page. |
+| `blogPostComponent` | `string` | `'@theme/BlogPostPage'` | Root component of each blog post page. |
+| `blogTagsListComponent` | `string` | `'@theme/BlogTagsListPage'` | Root component of the tags list page. |
+| `blogTagsPostsComponent` | `string` | `'@theme/BlogTagsPostsPage'` | Root component of the "posts containing tag" page. |
+| `blogArchiveComponent` | `string` | `'@theme/BlogArchivePage'` | Root component of the blog archive page. |
+| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
+| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. |
+| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
+| `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` | `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.createFeedItems` | CreateFeedItemsFn \| undefined | `undefined` | An optional function which can be used to transform and / or filter the items in the feed. |
+| `feedOptions.limit` | `number \| null \| false` | `20` | Limits the feed to the specified number of posts, `false` or `null` for all entries. Defaults to `20`. |
+| `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. |
+| `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
+| `sortPosts` | 'descending' \| 'ascending' | `'descending'` | Governs the direction of blog post sorting. |
+
+```mdx-code-block
+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. |
+| `tagsBasePath` | `string` | `'tags'` | URL route for the tags list page of your site. It is prepended to the `routeBasePath`. |
+| `include` | `string[]` | `['**/*.{md,mdx}']` | Array of glob patterns matching Markdown files to be built, relative to the content path. |
+| `exclude` | `string[]` | _See example configuration_ | Array of glob patterns matching Markdown files to be excluded. Serves as refinement based on the `include` option. |
+| `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/items#collapsible-categories) |
+| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. See also [Expanded categories by default](/docs/sidebar/items#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/autogenerated#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/autogenerated#using-number-prefixes) |
+| `docsRootComponent` | `string` | `'@theme/DocsRoot'` | Parent component of all the docs plugin pages (including all versions). Stays mounted when navigation between docs pages and versions. |
+| `docVersionRootComponent` | `string` | `'@theme/DocVersionLayout'` | Parent component of all docs pages of an individual version (doc pages with sidebars, tags pages). Stays mounted when navigation between pages of that specific version. |
+| `docRootComponent` | `string` | `'@theme/DocPage'` | Parent component of all doc pages with sidebars (regular docs pages, category generated index pages). Stays mounted when navigation between such pages. |
+| `docItemComponent` | `string` | `'@theme/DocItem'` | Main doc container, with TOC, pagination, etc. |
+| `docTagsListComponent` | `string` | `'@theme/DocTagsListPage'` | Root component of the tags list page |
+| `docTagDocListComponent` | `string` | `'@theme/DocTagDocListPage'` | Root component of the "docs containing tag X" page. |
+| `docCategoryGeneratedIndexComponent` | `string` | `'@theme/DocCategoryGeneratedIndexPage'` | Root component of the generated category index page. |
+| `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
+| `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. |
+| `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
+| `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
+| `showLastUpdateAuthor` | `boolean` | `false` | Whether to display the author who last updated the doc. |
+| `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the doc was updated. |
+| `breadcrumbs` | `boolean` | `true` | Enable or disable the breadcrumbs on doc pages. |
+| `disableVersioning` | `boolean` | `false` | Explicitly disable versioning even when multiple versions exist. This will make the site only include the current version. Will error if `includeCurrentVersion: false` and `disableVersioning: true`. |
+| `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. |
+
+```mdx-code-block
+string \| null | Next doc in the sidebar | The ID of the documentation you want the "Next" pagination to link to. Use `null` to disable showing "Next" for this page. |
+| `pagination_prev` | string \| null | Previous doc in the sidebar | The ID of the documentation you want the "Previous" pagination to link to. Use `null` to disable showing "Previous" for this page. |
+| `parse_number_prefixes` | `boolean` | `numberPrefixParser` plugin option | Whether number prefix parsing is disabled on this doc. See also [Using number prefixes](/docs/sidebar/autogenerated#using-number-prefixes). |
+| `custom_edit_url` | string \| null | Computed using the `editUrl` plugin option | The URL for editing this document. Use `null` to disable showing "Edit this page" for this page. |
+| `keywords` | `string[]` | `undefined` | Keywords meta tag for the document page, for search engines. |
+| `description` | `string` | The first line of Markdown content | The description of your document, which will become the `` and `` in ``, used by search engines. |
+| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
+| `slug` | `string` | File path | Allows to customize the document URL (`/string \| string[] | **Required** | The tracking ID of your gtag service. It is possible to provide multiple ids. |
+| `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. |
+
+```mdx-code-block
+
+
+ )}>
+ This component crashed because of error: {error.message}.
+ +
+
+);
+```
+
+#### `to`: string {#to-string}
+
+The target location to navigate to. Example: `/docs/introduction`.
+
+```jsx
+
+```
+
+:::tip
+
+Prefer this component to vanilla `` tags because Docusaurus does a lot of optimizations (e.g. broken path detection, prefetching, applying base URL...) if you use ``.
+
+:::
+
+### `+ {/* highlight-next-line */} + Check out my blog! +
++ {/* highlight-next-line */} + Follow me on Twitter! +
+
+ {/* highlight-start */}
+
+ Welcome to my website
+
+ {/* highlight-end */}
+
+
+ {/* highlight-start */}
+
+ );
+};
+```
+
+:::note
+
+The `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side.
+
+:::
+
+### `useIsBrowser` {#useIsBrowser}
+
+Returns `true` when the React app has successfully hydrated in the browser.
+
+:::warning
+
+Use this hook instead of `typeof windows !== 'undefined'` in React rendering logic.
+
+The first client-side render output (in the browser) **must be exactly the same** as the server-side render output (Node.js). Not following this rule can lead to unexpected hydration behaviors, as described in [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/).
+
+:::
+
+Usage example:
+
+```jsx
+import React from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+
+const MyComponent = () => {
+ // highlight-start
+ const isBrowser = useIsBrowser();
+ // highlight-end
+ return {siteConfig.title}
+{siteMetadata.siteVersion}
+ {siteMetadata.docusaurusVersion}
+ {/* highlight-end */}
+ {isBrowser ? 'Client' : 'Server'}
;
+};
+```
+
+### `useBaseUrl` {#useBaseUrl}
+
+React hook to prepend your site `baseUrl` to a string.
+
+:::warning
+
+**Don't use it for regular links!**
+
+The `/baseUrl/` prefix is automatically added to all **absolute paths** by default:
+
+- Markdown: `[link](/my/path)` will link to `/baseUrl/my/path`
+- React: `link` will link to `/baseUrl/my/path`
+
+:::
+
+#### Options {#options}
+
+```ts
+type BaseUrlOptions = {
+ forcePrependBaseUrl: boolean;
+ absolute: boolean;
+};
+```
+
+#### Example usage: {#example-usage}
+
+```jsx
+import React from 'react';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+const SomeImage = () => {
+ // highlight-start
+ const imgSrc = useBaseUrl('/img/myImage.png');
+ // highlight-end
+ return .default})
+```
+
+:::
+
+### `useBaseUrlUtils` {#useBaseUrlUtils}
+
+Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base URL.
+
+- `withBaseUrl`: useful if you need to add base URLs to multiple URLs at once.
+
+```jsx
+import React from 'react';
+import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+
+const Component = () => {
+ const urls = ['/a', '/b'];
+ // highlight-start
+ const {withBaseUrl} = useBaseUrlUtils();
+ const urlsWithBaseUrl = urls.map(withBaseUrl);
+ // highlight-end
+ return {/* ... */}
;
+};
+```
+
+### `useGlobalData` {#useGlobalData}
+
+React hook to access Docusaurus global data created by all the plugins.
+
+Global data is namespaced by plugin name then by plugin ID.
+
+:::info
+
+Plugin ID is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.
+
+:::
+
+```ts
+type GlobalData = Record<
+ PluginName,
+ Record<
+ PluginId, // "default" by default
+ any // plugin-specific data
+ >
+>;
+```
+
+Usage example:
+
+```jsx
+import React from 'react';
+// highlight-next-line
+import useGlobalData from '@docusaurus/useGlobalData';
+
+const MyComponent = () => {
+ // highlight-start
+ const globalData = useGlobalData();
+ const myPluginData = globalData['my-plugin']['default'];
+ return {myPluginData.someAttribute}
;
+ // highlight-end
+};
+```
+
+:::tip
+
+Inspect your site's global data at `./docusaurus/globalData.json`
+
+:::
+
+### `usePluginData` {#usePluginData}
+
+Access global data created by a specific plugin instance.
+
+This is the most convenient hook to access plugin global data and should be used most of the time.
+
+`pluginId` is optional if you don't use multi-instance plugins.
+
+```ts
+function usePluginData(
+ pluginName: string,
+ pluginId?: string,
+ options?: {failfast?: boolean},
+);
+```
+
+Usage example:
+
+```jsx
+import React from 'react';
+// highlight-next-line
+import {usePluginData} from '@docusaurus/useGlobalData';
+
+const MyComponent = () => {
+ // highlight-start
+ const myPluginData = usePluginData('my-plugin');
+ return {myPluginData.someAttribute}
;
+ // highlight-end
+};
+```
+
+### `useAllPluginInstancesData` {#useAllPluginInstancesData}
+
+Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.
+
+```ts
+function useAllPluginInstancesData(
+ pluginName: string,
+ options?: {failfast?: boolean},
+);
+```
+
+Usage example:
+
+```jsx
+import React from 'react';
+// highlight-next-line
+import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';
+
+const MyComponent = () => {
+ // highlight-start
+ const allPluginInstancesData = useAllPluginInstancesData('my-plugin');
+ const myPluginData = allPluginInstancesData['default'];
+ return {myPluginData.someAttribute}
;
+ // highlight-end
+};
+```
+
+### `useBrokenLinks` {#useBrokenLinks}
+
+React hook to access the Docusaurus broken link checker APIs, exposing a way for a Docusaurus pages to report and collect their links and anchors. :::warning This is an **advanced** API that **most Docusaurus users don't need to use directly**.
+
+It is already **built-in** in existing high-level components:
+
+- the [``](#link) component will collect links for you
+- the `@theme/Heading` (used for Markdown headings) will collect anchors
+
+Use `useBrokenLinks()` if you implement your own `
+ 
', // The HTML to be rendered
+ defaultStyle: true, // Use the default menu item styling
+ },
+ // highlight-end
+ ],
+};
+```
+
+:::tip
+
+The menu item is already wrapped in an `