From b27cbf9cbe1a58b74fe65dc096eba5ffbc0cde1f Mon Sep 17 00:00:00 2001 From: tgreyuk Date: Tue, 7 Jan 2025 19:56:40 +0000 Subject: [PATCH] fix(docusaurus): expose CSS class name to deprecated sidebar items --- .changeset/chatty-houses-laugh.md | 5 +++ devtools/examples/docusaurus/css/typedoc.css | 3 ++ .../examples/docusaurus/docusaurus.config.js | 5 ++- docs/global.css | 3 +- docs/pages/plugins/docusaurus/options.mdx | 11 +++++-- docs/pages/plugins/docusaurus/sidebar.mdx | 12 +++++-- .../docusaurus.config.js | 2 +- .../src/options/declarations.ts | 21 ++++++++++-- .../src/options/options.ts | 1 + .../src/plugins/typedoc.ts | 1 + .../src/types/options.ts | 1 + .../src/utils/get-sidebar.ts | 32 +++++++++---------- .../__snapshots__/docusaurus.spec.ts.snap | 5 +-- 13 files changed, 72 insertions(+), 30 deletions(-) create mode 100644 .changeset/chatty-houses-laugh.md create mode 100644 devtools/examples/docusaurus/css/typedoc.css diff --git a/.changeset/chatty-houses-laugh.md b/.changeset/chatty-houses-laugh.md new file mode 100644 index 000000000..ab7be9aab --- /dev/null +++ b/.changeset/chatty-houses-laugh.md @@ -0,0 +1,5 @@ +--- +'docusaurus-plugin-typedoc': patch +--- + +- Expose CSS class name to deprecated sidebar items (#747). diff --git a/devtools/examples/docusaurus/css/typedoc.css b/devtools/examples/docusaurus/css/typedoc.css new file mode 100644 index 000000000..257896e90 --- /dev/null +++ b/devtools/examples/docusaurus/css/typedoc.css @@ -0,0 +1,3 @@ +.typedoc-sidebar-is-deprecated { + text-decoration: line-through; +} diff --git a/devtools/examples/docusaurus/docusaurus.config.js b/devtools/examples/docusaurus/docusaurus.config.js index 14851340f..cbf9e400a 100644 --- a/devtools/examples/docusaurus/docusaurus.config.js +++ b/devtools/examples/docusaurus/docusaurus.config.js @@ -153,7 +153,9 @@ const config = { editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', }, - theme: {}, + theme: { + customCss: ['./css/typedoc.css'], + }, }), ], ], @@ -166,6 +168,7 @@ const config = { sidebar: { autoCollapseCategories: true, }, + navbar: { title: 'My Site', logo: { diff --git a/docs/global.css b/docs/global.css index f9c2a442a..6dcc62b41 100644 --- a/docs/global.css +++ b/docs/global.css @@ -15,8 +15,7 @@ .nextra-toc a[href^='#non-breaking-changes'], .nextra-toc a[href^='#architectural-changes'], .nextra-toc a[href^='#structural-changes'], -.nextra-toc a[href^='#breaking-changes'], -.nextra-toc a[href^='#deprecated'] { +.nextra-toc a[href^='#breaking-changes'] { display: none; } blockquote { diff --git a/docs/pages/plugins/docusaurus/options.mdx b/docs/pages/plugins/docusaurus/options.mdx index 977ae032a..0ef47aa7a 100644 --- a/docs/pages/plugins/docusaurus/options.mdx +++ b/docs/pages/plugins/docusaurus/options.mdx @@ -30,21 +30,26 @@ The following options are exposed by this plugin: > Accepts a key/value object. -**sidebar.autoConfiguration** +**autoConfiguration** Set to `false` to disable sidebar generation. Defaults to `true`. -**sidebar.pretty** +**pretty** Pretty format the sidebar JSON. +**deprecatedItemClassName** + +The class name to apply to deprecated items in the sidebar. Defaults to `"typedoc-sidebar-item-deprecated"`. + Please see the [sidebar guide](https:/typedoc-plugin-markdown.org/plugins/docusaurus/sidebar) for additional information on sidebar setup. ```json filename="typedoc.json" { "sidebar": { "autoConfiguration": true, - "pretty": false + "pretty": false, + "deprecatedItemClassName": "typedoc-sidebar-item-deprecated" } } ``` diff --git a/docs/pages/plugins/docusaurus/sidebar.mdx b/docs/pages/plugins/docusaurus/sidebar.mdx index 5c0764174..2221ab4f7 100644 --- a/docs/pages/plugins/docusaurus/sidebar.mdx +++ b/docs/pages/plugins/docusaurus/sidebar.mdx @@ -1,5 +1,3 @@ -import { Callout } from 'nextra/components'; - # Sidebar A docusaurus sidebar file named `typedoc-sidebar.cjs` is published to the relevant output directory along with the generated markdown documentation. @@ -62,5 +60,15 @@ presets: [ }), ], ], +``` + +## Deprecated sidebar items +Deprecated sidebar items have a configurable CSS class name attached to them (see [sidebar options](/plugins/docusaurus/options#sidebar) +and can be styled using CSS https://docusaurus.io/docs/styling-layout#global-styles. + +```css +.typedoc-sidebar-item-deprecated { + text-decoration: line-through; +} ``` diff --git a/packages/docusaurus-plugin-typedoc/docusaurus.config.js b/packages/docusaurus-plugin-typedoc/docusaurus.config.js index e55aaaca4..15b9500dd 100644 --- a/packages/docusaurus-plugin-typedoc/docusaurus.config.js +++ b/packages/docusaurus-plugin-typedoc/docusaurus.config.js @@ -32,7 +32,7 @@ const config = { entryPoints: ['./test/stubs/src/module-1.ts'], out: './test/out/global-members', readme: 'none', - sidebar: { pretty: true }, + sidebar: { pretty: true, deprecatedItemClassName: 'is-deprecated' }, fileExtension: '.mdx', disableSources: true, hidePageHeader: true, diff --git a/packages/docusaurus-plugin-typedoc/src/options/declarations.ts b/packages/docusaurus-plugin-typedoc/src/options/declarations.ts index bf8298ba4..31923a5c0 100644 --- a/packages/docusaurus-plugin-typedoc/src/options/declarations.ts +++ b/packages/docusaurus-plugin-typedoc/src/options/declarations.ts @@ -15,14 +15,18 @@ export const docusaurusConfigOptions: Partial = { }; /** - * **sidebar.autoConfiguration** + * **autoConfiguration** * * Set to `false` to disable sidebar generation. Defaults to `true`. * - * **sidebar.pretty** + * **pretty** * * Pretty format the sidebar JSON. * + * **deprecatedItemClassName** + * + * The class name to apply to deprecated items in the sidebar. Defaults to `"typedoc-sidebar-item-deprecated"`. + * * Please see the [sidebar guide](https:/typedoc-plugin-markdown.org/plugins/docusaurus/sidebar) for additional information on sidebar setup. * */ @@ -30,4 +34,17 @@ export const sidebar: Partial = { help: 'Configures the autogenerated Docusaurus sidebar.', type: ParameterType.Mixed, defaultValue: DEFAULT_SIDEBAR_OPTIONS, + validate(value) { + if (typeof value !== 'object') { + console.warn('[typedoc-plugin-markdown] Sidebar must be an object.'); + } + const invalidKeys = Object.keys(value as {}).filter( + (key) => !Object.keys(DEFAULT_SIDEBAR_OPTIONS).includes(key), + ); + if (invalidKeys.length > 0) { + console.warn( + `[typedoc-plugin-markdown] Invalid keys in sidebar options: ${invalidKeys.join(', ')}`, + ); + } + }, }; diff --git a/packages/docusaurus-plugin-typedoc/src/options/options.ts b/packages/docusaurus-plugin-typedoc/src/options/options.ts index 13cc27b22..b78c787d3 100644 --- a/packages/docusaurus-plugin-typedoc/src/options/options.ts +++ b/packages/docusaurus-plugin-typedoc/src/options/options.ts @@ -3,6 +3,7 @@ import { presets } from './presets.js'; export const DEFAULT_SIDEBAR_OPTIONS = { autoConfiguration: true, pretty: false, + deprecatedItemClassName: 'typedoc-sidebar-item-deprecated', }; const DEFAULT_PLUGIN_OPTIONS = { diff --git a/packages/docusaurus-plugin-typedoc/src/plugins/typedoc.ts b/packages/docusaurus-plugin-typedoc/src/plugins/typedoc.ts index 351ab51c0..ac544721b 100644 --- a/packages/docusaurus-plugin-typedoc/src/plugins/typedoc.ts +++ b/packages/docusaurus-plugin-typedoc/src/plugins/typedoc.ts @@ -64,6 +64,7 @@ export function load(app: MarkdownApplication) { const sidebarJson = getSidebar( output.navigation, baseDir, + sidebar, numberPrefixParser, ); diff --git a/packages/docusaurus-plugin-typedoc/src/types/options.ts b/packages/docusaurus-plugin-typedoc/src/types/options.ts index de0e9e00d..c0d6ea6b8 100644 --- a/packages/docusaurus-plugin-typedoc/src/types/options.ts +++ b/packages/docusaurus-plugin-typedoc/src/types/options.ts @@ -19,4 +19,5 @@ export interface PluginOptions { export interface Sidebar { autoConfiguration: boolean; pretty: boolean; + deprecatedItemClassName: string; } diff --git a/packages/docusaurus-plugin-typedoc/src/utils/get-sidebar.ts b/packages/docusaurus-plugin-typedoc/src/utils/get-sidebar.ts index 1fee1fb60..a479093d3 100644 --- a/packages/docusaurus-plugin-typedoc/src/utils/get-sidebar.ts +++ b/packages/docusaurus-plugin-typedoc/src/utils/get-sidebar.ts @@ -1,13 +1,15 @@ import { NavigationItem } from 'typedoc-plugin-markdown'; +import { Sidebar } from '../types/options.js'; export function getSidebar( navigation: NavigationItem[], basePath: string, + options: Sidebar, numberPrefixParser?: any, ) { return navigation .map((navigationItem) => - getNavigationItem(navigationItem, basePath, numberPrefixParser), + getNavigationItem(navigationItem, basePath, options, numberPrefixParser), ) .filter((navItem) => Boolean(navItem)); } @@ -15,6 +17,7 @@ export function getSidebar( function getNavigationItem( navigationItem: NavigationItem, basePath: string, + options: Sidebar, numberPrefixParser?: any, ) { const navigationItemPath = navigationItem.path || (navigationItem as any).url; @@ -42,8 +45,13 @@ function getNavigationItem( if (navigationItem.children?.length) { return { type: 'category', - label: getNavigationLabel(navigationItem), - items: getSidebar(navigationItem.children, basePath, numberPrefixParser), + label: navigationItem.title, + items: getSidebar( + navigationItem.children, + basePath, + options, + numberPrefixParser, + ), ...(id && { link: { type: 'doc', @@ -57,20 +65,10 @@ function getNavigationItem( ? { type: 'doc', id, - label: getNavigationLabel(navigationItem), + label: navigationItem.title, + ...(navigationItem.isDeprecated && { + className: options.deprecatedItemClassName, + }), } : null; } - -function getNavigationLabel(navigationItem: NavigationItem) { - return navigationItem.isDeprecated - ? strikethrough(navigationItem.title) - : navigationItem.title; -} - -function strikethrough(label: string) { - return label - .split('') - .map((char) => char + '\u0336') - .join(''); -} diff --git a/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap b/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap index 5d8ebc00b..b0c344c9e 100644 --- a/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap +++ b/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap @@ -18,7 +18,7 @@ title: "test" exports[`Docusaurus: Defaults should render sidebar 1`] = ` "// @ts-check /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ -const typedocSidebar = { items: [{"type":"category","label":"links","items":[{"type":"category","label":"Enumerations","items":[{"type":"doc","id":"out/default/links/enumerations/CommentEnum","label":"CommentEnum"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/links/interfaces/CommentInterface","label":"CommentInterface"},{"type":"doc","id":"out/default/links/interfaces/CommentInterfaceExtended","label":"CommentInterfaceExtended"}]}],"link":{"type":"doc","id":"out/default/links/index"}},{"type":"category","label":"module-1","items":[{"type":"category","label":"CategoryA","items":[{"type":"doc","id":"out/default/module-1/classes/ClassA","label":"ClassA"}]},{"type":"category","label":"CategoryB","items":[{"type":"doc","id":"out/default/module-1/classes/ClassB","label":"ClassB"},{"type":"doc","id":"out/default/module-1/classes/ClassC","label":"C̶l̶a̶s̶s̶C̶"},{"type":"doc","id":"out/default/module-1/interfaces/InterfaceA","label":"InterfaceA"},{"type":"doc","id":"out/default/module-1/interfaces/InterfaceB","label":"InterfaceB"}]}],"link":{"type":"doc","id":"out/default/module-1/index"}},{"type":"category","label":"module-2","items":[{"type":"category","label":"Classes","items":[{"type":"doc","id":"out/default/module-2/classes/ClassA","label":"ClassA"},{"type":"doc","id":"out/default/module-2/classes/ClassB","label":"ClassB"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/module-2/interfaces/ClassC","label":"C̶l̶a̶s̶s̶C̶"},{"type":"doc","id":"out/default/module-2/interfaces/InterfaceA","label":"InterfaceA"},{"type":"doc","id":"out/default/module-2/interfaces/InterfaceB","label":"InterfaceB"}]}],"link":{"type":"doc","id":"out/default/module-2/index"}}]}; +const typedocSidebar = { items: [{"type":"category","label":"links","items":[{"type":"category","label":"Enumerations","items":[{"type":"doc","id":"out/default/links/enumerations/CommentEnum","label":"CommentEnum"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/links/interfaces/CommentInterface","label":"CommentInterface"},{"type":"doc","id":"out/default/links/interfaces/CommentInterfaceExtended","label":"CommentInterfaceExtended"}]}],"link":{"type":"doc","id":"out/default/links/index"}},{"type":"category","label":"module-1","items":[{"type":"category","label":"CategoryA","items":[{"type":"doc","id":"out/default/module-1/classes/ClassA","label":"ClassA"}]},{"type":"category","label":"CategoryB","items":[{"type":"doc","id":"out/default/module-1/classes/ClassB","label":"ClassB"},{"type":"doc","id":"out/default/module-1/classes/ClassC","label":"ClassC","className":"typedoc-sidebar-item-deprecated"},{"type":"doc","id":"out/default/module-1/interfaces/InterfaceA","label":"InterfaceA"},{"type":"doc","id":"out/default/module-1/interfaces/InterfaceB","label":"InterfaceB"}]}],"link":{"type":"doc","id":"out/default/module-1/index"}},{"type":"category","label":"module-2","items":[{"type":"category","label":"Classes","items":[{"type":"doc","id":"out/default/module-2/classes/ClassA","label":"ClassA"},{"type":"doc","id":"out/default/module-2/classes/ClassB","label":"ClassB"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/module-2/interfaces/ClassC","label":"ClassC","className":"typedoc-sidebar-item-deprecated"},{"type":"doc","id":"out/default/module-2/interfaces/InterfaceA","label":"InterfaceA"},{"type":"doc","id":"out/default/module-2/interfaces/InterfaceB","label":"InterfaceB"}]}],"link":{"type":"doc","id":"out/default/module-2/index"}}]}; module.exports = typedocSidebar.items;" `; @@ -152,7 +152,8 @@ const typedocSidebar = { items: [ { "type": "doc", "id": "out/global-members/classes/ClassC", - "label": "C̶l̶a̶s̶s̶C̶" + "label": "ClassC", + "className": "is-deprecated" }, { "type": "doc",