Add Markdown DocCard override

demo/examples/tests/docCards.yaml

@@ -0,0 +1,19 @@
+openapi: 3.0.3
+info:
+  title: DocCard Markdown Example
+  version: 1.0.0
+paths:
+  /docs:
+    get:
+      summary: Doc card operation
+      description: >
+        Returns documentation with **markdown** and <b>HTML</b> in descriptions.
+      tags:
+        - docCards
+      responses:
+        "200":
+          description: OK
+
+tags:
+  - name: docCards
+    description: This tag shows **markdown** and <b>HTML</b> in the doc card.

packages/docusaurus-plugin-openapi-docs/src/openapi/__fixtures__/docCards/openapi.yaml

@@ -0,0 +1,19 @@
+openapi: 3.0.3
+info:
+  title: DocCard Markdown Example
+  version: 1.0.0
+paths:
+  /docs:
+    get:
+      summary: Doc card operation
+      description: >
+        Returns documentation with **markdown** and <b>HTML</b> in descriptions.
+      tags:
+        - docCards
+      responses:
+        "200":
+          description: OK
+
+tags:
+  - name: docCards
+    description: This tag shows **markdown** and <b>HTML</b> in the doc card.

packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.test.ts

@@ -37,4 +37,22 @@ describe("openapi", () => {
       ).toBeDefined();
     });
   });
+
+  describe("doc card markdown", () => {
+    it("preserves markdown and html in tag descriptions", async () => {
+      const results = await readOpenapiFiles(
+        posixPath(path.join(__dirname, "__fixtures__/docCards"))
+      );
+      const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
+      expect(yaml).toBeTruthy();
+      const tag = yaml?.data.tags?.find((t) => t.name === "docCards");
+      expect(tag?.description).toBe(
+        "This tag shows **markdown** and <b>HTML</b> in the doc card."
+      );
+      const op = yaml?.data.paths?.["/docs"]?.get;
+      expect(op?.description?.trim()).toBe(
+        "Returns documentation with **markdown** and <b>HTML</b> in descriptions."
+      );
+    });
+  });
 });

packages/docusaurus-theme-openapi-docs/src/theme/DocCard/index.tsx

@@ -0,0 +1,142 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import React, { type ReactNode } from "react";
+
+import isInternalUrl from "@docusaurus/isInternalUrl";
+import Link from "@docusaurus/Link";
+import type {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from "@docusaurus/plugin-content-docs";
+import {
+  useDocById,
+  findFirstSidebarItemLink,
+} from "@docusaurus/plugin-content-docs/lib/client/docsUtils";
+import { usePluralForm } from "@docusaurus/theme-common";
+import { translate } from "@docusaurus/Translate";
+import type { Props } from "@theme/DocCard";
+import Heading from "@theme/Heading";
+import Markdown from "@theme/Markdown";
+import clsx from "clsx";
+
+import styles from "./styles.module.css";
+
+function useCategoryItemsPlural() {
+  const { selectMessage } = usePluralForm();
+  return (count: number) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          message: "1 item|{count} items",
+          id: "theme.docs.DocCard.categoryDescription.plurals",
+          description:
+            "The default description for a category card in the generated index about how many items this category includes",
+        },
+        { count }
+      )
+    );
+}
+
+function CardContainer({
+  className,
+  href,
+  children,
+}: {
+  className?: string;
+  href: string;
+  children: ReactNode;
+}): ReactNode {
+  return (
+    <Link
+      href={href}
+      className={clsx("card padding--lg", styles.cardContainer, className)}
+    >
+      {children}
+    </Link>
+  );
+}
+
+function CardLayout({
+  className,
+  href,
+  icon,
+  title,
+  description,
+}: {
+  className?: string;
+  href: string;
+  icon: ReactNode;
+  title: string;
+  description?: string;
+}): ReactNode {
+  return (
+    <CardContainer href={href} className={className}>
+      <Heading
+        as="h2"
+        className={clsx("text--truncate", styles.cardTitle)}
+        title={title}
+      >
+        {icon} {title}
+      </Heading>
+      {description && (
+        <Markdown
+          className={clsx("text--truncate", styles.cardDescription)}
+          title={description}
+        >
+          {description}
+        </Markdown>
+      )}
+    </CardContainer>
+  );
+}
+
+function CardCategory({ item }: { item: PropSidebarItemCategory }): ReactNode {
+  const href = findFirstSidebarItemLink(item);
+  const categoryItemsPlural = useCategoryItemsPlural();
+
+  // Unexpected: categories that don't have a link have been filtered upfront
+  if (!href) {
+    return null;
+  }
+
+  return (
+    <CardLayout
+      className={item.className}
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={item.description ?? categoryItemsPlural(item.items.length)}
+    />
+  );
+}
+
+function CardLink({ item }: { item: PropSidebarItemLink }): ReactNode {
+  const icon = isInternalUrl(item.href) ? "📄️" : "🔗";
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <CardLayout
+      className={item.className}
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={item.description ?? doc?.description}
+    />
+  );
+}
+
+export default function DocCard({ item }: Props): ReactNode {
+  switch (item.type) {
+    case "link":
+      return <CardLink item={item} />;
+    case "category":
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}

packages/docusaurus-theme-openapi-docs/src/theme/DocCard/styles.module.css

@@ -0,0 +1,34 @@
+/* ========================================================================== */
+/* Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+.cardContainer {
+  --ifm-link-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-color: var(--ifm-color-emphasis-700);
+  --ifm-link-hover-decoration: none;
+
+  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: all var(--ifm-transition-fast) ease;
+  transition-property: border, box-shadow;
+}
+
+.cardContainer:hover {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
+}
+
+.cardContainer *:last-child {
+  margin-bottom: 0;
+}
+
+.cardTitle {
+  font-size: 1.2rem;
+}
+
+.cardDescription {
+  font-size: 0.8rem;
+}