Merge pull request #937 from PaloAltoNetworks/layout-paginator

Conditionally set col width for api doc layout

Author: sserrata

packages/docusaurus-theme-openapi-docs/src/plugin-content-docs.d.ts

@@ -15,4 +15,6 @@ declare module "@docusaurus/plugin-content-docs/client" {
     children: ReactNode;
     content: PropDocContent;
   });
+
+  export function useDoc();
 }

packages/docusaurus-theme-openapi-docs/src/theme-classic.d.ts

@@ -27,8 +27,6 @@ declare module "@docusaurus/theme-common/internal" {
   export interface LineProps extends ILineProps {}
   export interface CodeBlockProps extends ICodeBlockProps {}
 
-  export function useDoc();
-
   export function usePrismTheme(): PrismTheme;
 
   export function sanitizeTabsChildren(children: TabProps["children"]);

packages/docusaurus-theme-openapi-docs/src/theme-openapi.d.ts

@@ -54,6 +54,10 @@ declare module "@theme/ApiItem/hooks" {
 }
 
 declare module "@theme/ApiItem/Layout" {
+  export interface Props {
+    readonly children: JSX.Element;
+  }
+
   export default function Layout(props: any): JSX.Element;
 }
 

packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/Layout/index.tsx

@@ -0,0 +1,82 @@
+/* ============================================================================
+ * 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 from "react";
+
+import { useDoc } from "@docusaurus/plugin-content-docs/client";
+import { useWindowSize } from "@docusaurus/theme-common";
+import type { Props } from "@theme/ApiItem/Layout";
+import ContentVisibility from "@theme/ContentVisibility";
+import DocBreadcrumbs from "@theme/DocBreadcrumbs";
+import DocItemContent from "@theme/DocItem/Content";
+import DocItemFooter from "@theme/DocItem/Footer";
+import DocItemPaginator from "@theme/DocItem/Paginator";
+import DocItemTOCDesktop from "@theme/DocItem/TOC/Desktop";
+import DocItemTOCMobile from "@theme/DocItem/TOC/Mobile";
+import DocVersionBadge from "@theme/DocVersionBadge";
+import DocVersionBanner from "@theme/DocVersionBanner";
+import clsx from "clsx";
+
+import styles from "./styles.module.css";
+
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const { frontMatter, toc } = useDoc();
+  const windowSize = useWindowSize();
+
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+
+  const desktop =
+    canRender && (windowSize === "desktop" || windowSize === "ssr") ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+
+export default function DocItemLayout({ children }: Props): JSX.Element {
+  const docTOC = useDocTOC();
+  const { metadata } = useDoc();
+  const { frontMatter } = useDoc();
+  const api = frontMatter.api;
+  return (
+    <div className="row">
+      <div className={clsx("col", !docTOC.hidden && styles.docItemCol)}>
+        <ContentVisibility metadata={metadata} />
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <div className="row">
+              <div className={clsx("col", api ? "col--7" : "col--12")}>
+                <DocItemFooter />
+              </div>
+            </div>
+          </article>
+          <div className="row">
+            <div className={clsx("col", api ? "col--7" : "col--12")}>
+              <DocItemPaginator />
+            </div>
+          </div>
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}

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

@@ -0,0 +1,17 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}

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

@@ -17,8 +17,8 @@ import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import { createAuth } from "@theme/ApiExplorer/Authorization/slice";
 import { createPersistanceMiddleware } from "@theme/ApiExplorer/persistanceMiddleware";
+import DocItemLayout from "@theme/ApiItem/Layout";
 import type { Props } from "@theme/DocItem";
-import DocItemLayout from "@theme/DocItem/Layout";
 import DocItemMetadata from "@theme/DocItem/Metadata";
 import clsx from "clsx";
 import { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";