Skip to content

Introduce support for Docusaurus 3.5.0+ #919

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 19, 2024
Merged

Introduce support for Docusaurus 3.5.0+ #919

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d01ff1e
upgrade to docusaurus 3.5.2
sserrata Aug 16, 2024
3a9b3df
refactor imports and add plugin-content-docs declaration
sserrata Aug 16, 2024
b06fdcc
add module mapper for neotraverse/legacy
sserrata Aug 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions demo/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@
"re-gen": "yarn clean-all && yarn gen-all"
},
"dependencies": {
"@docusaurus/core": "3.4.0",
"@docusaurus/plugin-google-gtag": "3.4.0",
"@docusaurus/preset-classic": "3.4.0",
"@docusaurus/core": "3.5.2",
"@docusaurus/plugin-google-gtag": "3.5.2",
"@docusaurus/preset-classic": "3.5.2",
"clsx": "^1.1.1",
"docusaurus-plugin-openapi-docs": "^3.0.2",
"docusaurus-theme-openapi-docs": "^3.0.2",
Expand Down
4 changes: 4 additions & 0 deletions jest.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,8 @@ module.exports = {
"<rootDir>/packages/docusaurus-plugin-openapi-docs/src",
"<rootDir>/packages/docusaurus-theme-openapi-docs/src",
],
moduleNameMapper: {
"^neotraverse/legacy$":
"<rootDir>/node_modules/neotraverse/dist/legacy/legacy.cjs",
},
};
18 changes: 18 additions & 0 deletions packages/docusaurus-theme-openapi-docs/src/plugin-content-docs.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
/* ============================================================================
* 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.
* ========================================================================== */

/// <reference types="@docusaurus/theme-classic" />

declare module "@docusaurus/plugin-content-docs/client" {
export function DocProvider({
children,
content,
}: {
children: ReactNode;
content: PropDocContent;
});
}
4 changes: 2 additions & 2 deletions packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
// @ts-nocheck
import React, { useState } from "react";

import { useDoc } from "@docusaurus/theme-common/internal";
import { useDoc } from "@docusaurus/plugin-content-docs/client";
import Accept from "@theme/ApiExplorer/Accept";
import Authorization from "@theme/ApiExplorer/Authorization";
import Body from "@theme/ApiExplorer/Body";
Expand All @@ -31,7 +31,7 @@ import { FormProvider, useForm } from "react-hook-form";

import makeRequest from "./makeRequest";

function Request({ item }: { item: NonNullable<ApiItem> }) {
function Request({ item }: { item: ApiItem }) {
const postman = new sdk.Request(item.postman);
const metadata = useDoc();
const { proxy, hide_send_button: hideSendButton } = metadata.frontMatter;
Expand Down
5 changes: 3 additions & 2 deletions packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Response/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@

import React from "react";

// @ts-ignore
import { useDoc } from "@docusaurus/plugin-content-docs/client";
import { usePrismTheme } from "@docusaurus/theme-common";
import { useDoc } from "@docusaurus/theme-common/internal";
import ApiCodeBlock from "@theme/ApiExplorer/ApiCodeBlock";
import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
import SchemaTabs from "@theme/SchemaTabs";
Expand Down Expand Up @@ -38,7 +39,7 @@ function formatXml(xml: string) {
return formatted.substring(1, formatted.length - 3);
}

function Response({ item }: { item: NonNullable<ApiItem> }) {
function Response({ item }: { item: ApiItem }) {
const metadata = useDoc();
const hideSendButton = metadata.frontMatter.hide_send_button;
const prismTheme = usePrismTheme();
Expand Down
84 changes: 0 additions & 84 deletions packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/Layout/index.tsx
View file
Open in desktop

This file was deleted.

17 changes: 0 additions & 17 deletions packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/Layout/styles.module.css
View file
Open in desktop

This file was deleted.

4 changes: 2 additions & 2 deletions packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@ import React from "react";

import BrowserOnly from "@docusaurus/BrowserOnly";
import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
import { DocProvider } from "@docusaurus/plugin-content-docs/client";
import { HtmlClassNameProvider } from "@docusaurus/theme-common";
import { DocProvider } from "@docusaurus/theme-common/internal";
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";
Copy link
Contributor

@IanVS IanVS Aug 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like this change caused a visual update to generated API pages. Previously, the pagination at the bottom of the page was constrained to the center portion of the page, now after this update, the pagination also stretches into the right sidebar. We prefer the way it was previously. Is there any way to restore that?

Before:
image

After:
Arc 2024-08-27 08 48 39

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch @IanVS! I thought I could get away with not including Layout in our theme but didn't notice this side effect. Should be an easy fix.

If you need a fix sooner, you can swizzle Layout and use the useDoc hook to extract api from front matter, which can be used to conditionally set the footer/paginator col width:

Snippet:

<div className="row">
  <div className={clsx("col", !docTOC.hidden && styles.docItemCol)}>
    {unlisted && <Unlisted />}
    <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>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I caught it because of a visual regression testing tool, have you considered adding something like that to the demo, to catch small changes like this that are potentially easy to miss?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have - would you be willing to share your setup? I know Docusaurus uses Playwright + Argos, but I was hoping for something self-contained that can run entirely in GH Actions. Thanks!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have used Percy in the past and recently switched to using lost-pixel. I'm using their platform version via a github action (which is free for open source projects), but they also have a purely open-source self-hosted model available that would probably meet your needs from what I can tell.

import DocItemMetadata from "@theme/DocItem/Metadata";
import clsx from "clsx";
import { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
Expand Down
Loading
Loading