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},
       {