diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts index 861a0b711fa0..7046cee91cbb 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts @@ -210,6 +210,19 @@ describe('validateDocFrontMatter sidebar_position', () => { }); }); +describe('validateDocFrontMatter sidebar_custom_props', () => { + testField({ + prefix: 'sidebar_custom_props', + validFrontMatters: [ + {sidebar_custom_props: {}}, + {sidebar_custom_props: {prop: 'custom', number: 1, boolean: true}}, + ], + invalidFrontMatters: [ + [{sidebar_custom_props: ''}, 'must be of type object'], + ], + }); +}); + describe('validateDocFrontMatter custom_edit_url', () => { testField({ prefix: 'custom_edit_url', diff --git a/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts b/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts index 432c9ea7aa9f..72e085b070f9 100644 --- a/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts +++ b/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts @@ -30,6 +30,7 @@ const DocFrontMatterSchema = Joi.object({ sidebar_label: Joi.string(), sidebar_position: Joi.number(), sidebar_class_name: Joi.string(), + sidebar_custom_props: Joi.object().unknown(), displayed_sidebar: Joi.string().allow(null), tags: FrontMatterTagsSchema, pagination_label: Joi.string(), diff --git a/packages/docusaurus-plugin-content-docs/src/props.ts b/packages/docusaurus-plugin-content-docs/src/props.ts index 88c154051952..c65efa9e47a4 100644 --- a/packages/docusaurus-plugin-content-docs/src/props.ts +++ b/packages/docusaurus-plugin-content-docs/src/props.ts @@ -52,7 +52,8 @@ Available document ids are: label: sidebarLabel || item.label || title, href: permalink, className: item.className, - customProps: item.customProps, + customProps: + item.customProps ?? docMetadata.frontMatter.sidebar_custom_props, docId: docMetadata.unversionedId, }; }; diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index e4a96f107949..f48ccb505854 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -58,6 +58,7 @@ export type DocFrontMatter = { sidebar_label?: string; sidebar_position?: number; sidebar_class_name?: string; + sidebar_custom_props?: Record; displayed_sidebar?: string | null; pagination_label?: string; custom_edit_url?: string | null; diff --git a/website/_dogfooding/_docs tests/tests/custom-props/_category_.json b/website/_dogfooding/_docs tests/tests/custom-props/_category_.json new file mode 100644 index 000000000000..844af9fb2bcf --- /dev/null +++ b/website/_dogfooding/_docs tests/tests/custom-props/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Custom Props" +} diff --git a/website/_dogfooding/_docs tests/tests/custom-props/doc-with-custom-props.md b/website/_dogfooding/_docs tests/tests/custom-props/doc-with-custom-props.md new file mode 100644 index 000000000000..486859a3557b --- /dev/null +++ b/website/_dogfooding/_docs tests/tests/custom-props/doc-with-custom-props.md @@ -0,0 +1,10 @@ +--- +sidebar_custom_props: + prop: custom + number: 1 + boolean: true +--- + +# Doc with Custom Props + +This doc has custom props. diff --git a/website/_dogfooding/_docs tests/tests/custom-props/doc-without-custom-props.md b/website/_dogfooding/_docs tests/tests/custom-props/doc-without-custom-props.md new file mode 100644 index 000000000000..2fc07a1e0a4b --- /dev/null +++ b/website/_dogfooding/_docs tests/tests/custom-props/doc-without-custom-props.md @@ -0,0 +1,3 @@ +# Doc Without Custom Props + +This doc doesn't have custom props. diff --git a/website/_dogfooding/_docs tests/tests/custom-props/index.md b/website/_dogfooding/_docs tests/tests/custom-props/index.md new file mode 100644 index 000000000000..5204dd5cccf5 --- /dev/null +++ b/website/_dogfooding/_docs tests/tests/custom-props/index.md @@ -0,0 +1,22 @@ +# Custom Props + +```mdx-code-block +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + +export const DocPropsList = ({items}) => ( + + + + + + {items.map((item, index) => ( + + + + + ))} +
Doc PageCustom Props
{item.label}{JSON.stringify(item.customProps)}
+); + + +``` diff --git a/website/docs/guides/docs/sidebar/autogenerated.md b/website/docs/guides/docs/sidebar/autogenerated.md index b85b49da7ec1..807de81571de 100644 --- a/website/docs/guides/docs/sidebar/autogenerated.md +++ b/website/docs/guides/docs/sidebar/autogenerated.md @@ -305,9 +305,9 @@ function isCategoryIndex({fileName, directories}) { ## Autogenerated sidebar metadata {#autogenerated-sidebar-metadata} -For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names). +For handwritten sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item because, by default, items within a sidebar slice will be generated in **alphabetical order** (using file and folder names). -**For docs**: use additional front matter. The `label` and `className` attributes now become `sidebar_label` and `sidebar_class_name`, while there's an additional `sidebar_position` front matter. +**For docs**: use additional front matter. The `label`, `className`, and `customProps` attributes are declared in front matter as `sidebar_label`, `sidebar_class_name`, and `sidebar_custom_props`, respectively. Position can be specified in the same way, via `sidebar_position` front matter. ```md title="docs/tutorials/tutorial-easy.md" --- diff --git a/website/docs/guides/docs/sidebar/items.md b/website/docs/guides/docs/sidebar/items.md index 456c6e603bbd..83ab2b06a839 100644 --- a/website/docs/guides/docs/sidebar/items.md +++ b/website/docs/guides/docs/sidebar/items.md @@ -3,13 +3,13 @@ toc_max_heading_level: 4 slug: /sidebar/items --- +# Sidebar items + ```mdx-code-block import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; ``` -# Sidebar items - We have introduced three types of item types in the example in the previous section: `doc`, `category`, and `link`, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later. - **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar @@ -31,6 +31,7 @@ type SidebarItemDoc = id: string; label: string; // Sidebar label text className?: string; // Class name for sidebar label + customProps?: Record; // Custom props } // Shorthand syntax @@ -46,20 +47,20 @@ module.exports = { // highlight-start { type: 'doc', - id: 'doc1', // document id + id: 'doc1', // document ID label: 'Getting started', // sidebar label }, // highlight-end // Shorthand syntax: // highlight-start - 'doc2', // document id + 'doc2', // document ID // highlight-end ], }; ``` -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. +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. :::note @@ -67,6 +68,12 @@ A `doc` item sets an [implicit sidebar association](#sidebar-association). Don't ::: +:::tip + +Sidebar custom props is a useful way to propagate arbitrary doc metadata to the client side, so you can get additional information when using any doc-related hook that fetches a doc object. + +::: + ## Link: link to any page {#sidebar-item-link} Use the `link` type to link to any page (internal or external) that is not a doc.