feat(content-docs): sidebar item type "html" for rendering pure markup (#6519)

Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/validation.test.ts

@@ -47,6 +47,42 @@ describe('validateSidebars', () => {
   });
 });
 
+describe('html item type', () => {
+  test('requires a value', () => {
+    const sidebars: SidebarsConfig = {
+      sidebar1: [
+        {
+          // @ts-expect-error - test missing value
+          type: 'html',
+        },
+      ],
+    };
+    expect(() => validateSidebars(sidebars))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "{
+        \\"type\\": \\"html\\",
+        \\"value\\" [1]: -- missing --
+      }
+      
+      [1] \\"value\\" is required"
+    `);
+  });
+
+  test('accepts valid values', () => {
+    const sidebars: SidebarsConfig = {
+      sidebar1: [
+        {
+          type: 'html',
+          value: '<p>Hello, World!</p>',
+          defaultStyle: true,
+          className: 'foo',
+        },
+      ],
+    };
+    validateSidebars(sidebars);
+  });
+});
+
 describe('validateCategoryMetadataFile', () => {
   // TODO add more tests
 

packages/docusaurus-plugin-content-docs/src/sidebars/types.ts

@@ -27,6 +27,12 @@ export type SidebarItemDoc = SidebarItemBase & {
   id: string;
 };
 
+export type SidebarItemHtml = SidebarItemBase & {
+  type: 'html';
+  value: string;
+  defaultStyle?: boolean;
+};
+
 export type SidebarItemLink = SidebarItemBase & {
   type: 'link';
   href: string;
@@ -87,6 +93,7 @@ export type SidebarCategoriesShorthand = {
 
 export type SidebarItemConfig =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemAutogenerated
   | SidebarItemCategoryConfig
@@ -108,6 +115,7 @@ export type NormalizedSidebarItemCategory = Expand<
 
 export type NormalizedSidebarItem =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | NormalizedSidebarItemCategory
   | SidebarItemAutogenerated;
@@ -131,6 +139,7 @@ export type SidebarItemCategoryWithGeneratedIndex =
 
 export type SidebarItem =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemCategory;
 
@@ -158,7 +167,12 @@ export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
 };
 
-export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
+export type PropSidebarItemHtml = SidebarItemHtml;
+
+export type PropSidebarItem =
+  | PropSidebarItemLink
+  | PropSidebarItemCategory
+  | PropSidebarItemHtml;
 export type PropSidebar = PropSidebarItem[];
 export type PropSidebars = {
   [sidebarId: string]: PropSidebar;

packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts

@@ -12,6 +12,7 @@ import type {
   SidebarItemBase,
   SidebarItemAutogenerated,
   SidebarItemDoc,
+  SidebarItemHtml,
   SidebarItemLink,
   SidebarItemCategoryConfig,
   SidebarItemCategoryLink,
@@ -48,6 +49,12 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append<SidebarItemDoc>({
   label: Joi.string(),
 });
 
+const sidebarItemHtmlSchema = sidebarItemBaseSchema.append<SidebarItemHtml>({
+  type: 'html',
+  value: Joi.string().required(),
+  defaultStyle: Joi.boolean().default(false),
+});
+
 const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
   type: 'link',
   href: URISchema.required(),
@@ -117,6 +124,7 @@ const sidebarItemSchema: Joi.Schema<SidebarItemConfig> = Joi.object()
         is: Joi.string().valid('doc', 'ref').required(),
         then: sidebarItemDocSchema,
       },
+      {is: 'html', then: sidebarItemHtmlSchema},
       {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
       {is: 'category', then: sidebarItemCategorySchema},
       {

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/index.tsx

@@ -32,6 +32,7 @@ import type {
 
 import styles from './styles.module.css';
 import useIsBrowser from '@docusaurus/useIsBrowser';
+import type {SidebarItemHtml} from '@docusaurus/plugin-content-docs/src/sidebars/types';
 
 export default function DocSidebarItem({
   item,
@@ -40,6 +41,8 @@ export default function DocSidebarItem({
   switch (item.type) {
     case 'category':
       return <DocSidebarItemCategory item={item} {...props} />;
+    case 'html':
+      return <DocSidebarItemHtml item={item} {...props} />;
     case 'link':
     default:
       return <DocSidebarItemLink item={item} {...props} />;
@@ -216,6 +219,29 @@ function DocSidebarItemCategory({
   );
 }
 
+function DocSidebarItemHtml({
+  item,
+  level,
+  index,
+}: Props & {item: SidebarItemHtml}) {
+  const {value, defaultStyle, className} = item;
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        defaultStyle && `${styles.menuHtmlItem} menu__list-item`,
+        className,
+      )}
+      key={index}
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{
+        __html: value,
+      }}
+    />
+  );
+}
+
 function DocSidebarItemLink({
   item,
   onItemClick,

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/styles.module.css

@@ -17,4 +17,9 @@
   .menuLinkText.hasHref {
     cursor: pointer;
   }
+
+  .menuHtmlItem {
+    padding: var(--ifm-menu-link-padding-vertical)
+      var(--ifm-menu-link-padding-horizontal);
+  }
 }

packages/docusaurus-theme-common/src/utils/__tests__/docsUtils.test.tsx

@@ -226,9 +226,11 @@ describe('docsUtils', () => {
           testCategory({
             href: undefined,
             items: [
+              {type: 'html', value: '<p>test1</p>'},
               testCategory({
                 href: undefined,
                 items: [
+                  {type: 'html', value: '<p>test2</p>'},
                   testCategory({
                     href: '/itemPath',
                   }),

packages/docusaurus-theme-common/src/utils/docsUtils.tsx

@@ -123,12 +123,13 @@ export function findFirstCategoryLink(
   for (const subItem of item.items) {
     if (subItem.type === 'link') {
       return subItem.href;
-    }
-    if (subItem.type === 'category') {
+    } else if (subItem.type === 'category') {
       const categoryLink = findFirstCategoryLink(subItem);
       if (categoryLink) {
         return categoryLink;
       }
+    } else if (subItem.type === 'html') {
+      // skip
     } else {
       throw new Error(
         `Unexpected category item type for ${JSON.stringify(subItem)}`,