fix(docusaurus): expose CSS class name to deprecated sidebar items

typedoc2md · Jan 9, 2025 · 09ec0ca · 09ec0ca
1 parent 11b6831
commit 09ec0ca
Show file tree

Hide file tree

Showing 13 changed files with 59 additions and 30 deletions.
diff --git a/.changeset/chatty-houses-laugh.md 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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, deprecatedClassName: '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
@@ -15,14 +15,18 @@ export const docusaurusConfigOptions: Partial<DeclarationOption> = {
 };
 
 /**
- * **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.
  *
  */

diff --git 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
@@ -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
@@ -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
@@ -1,20 +1,23 @@
 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));
 }
 
 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
@@ -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": "typedoc-sidebar-item-deprecated"
       },
       {
         "type": "doc",