[docs] Render the Moodle Marketplace API reference with Redocusaurus

docusaurus.config.js

@@ -21,6 +21,7 @@ import MoodleBannerRemark from './src/remark/moodleBanner.js';
 import TrackerLinksRemark from './src/remark/trackerLinks.js';
 import UnversionedDocsLinksRemark from './src/remark/unversionedDocsLinks.js';
 import * as nextVersion from './nextVersion.js';
+import { updateMarketplaceApiSpec } from './src/utils/marketplaceApiSpec.js';
 
 // eslint-disable global-require
 
@@ -122,6 +123,25 @@ const config = {
                 },
             }),
         ],
+
+        // Moodle Marketplace API reference.
+        // Rendered with Redoc in general/community/plugincontribution/moodlemarketplaceapi.mdx.
+        // The spec is refreshed from the Marketplace on every build (see the default export below).
+        [
+            'redocusaurus',
+            {
+                specs: [
+                    {
+                        id: 'marketplace-api',
+                        spec: 'static/marketplace-api/openapi.json',
+                        url: '/marketplace-api/openapi.json',
+                    },
+                ],
+                theme: {
+                    primaryColor: '#bd5b00',
+                },
+            },
+        ],
     ],
 
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
@@ -241,4 +261,10 @@ const config = {
     ],
 };
 
-export default config;
+export default async function createConfig() {
+    // Keep the Marketplace API reference up to date.
+    // The committed copy is used if the Marketplace is unreachable.
+    await updateMarketplaceApiSpec();
+
+    return config;
+}

general/community/plugincontribution/moodlemarketplaceapi.mdx

@@ -0,0 +1,17 @@
+---
+title: Moodle Marketplace API
+sidebar_position: 2
+sidebar_label: Moodle Marketplace API
+hide_title: true
+hide_table_of_contents: true
+description: Reference documentation for the Moodle Marketplace API.
+tags:
+  - Guidelines for contributors
+  - Plugins
+  - Plugin documentation
+  - Moodle Marketplace
+---
+
+import ApiDocMdx from '@theme/ApiDocMdx';
+
+<ApiDocMdx id="marketplace-api" />

general/community/plugincontribution/pluginsdirectory/api.md

@@ -9,7 +9,7 @@ tags:
 
 :::warning
 
-This page describes the Plugins Directory API, not [Moodle Marketplace APIs](general/community/plugincontribution/moodlemarketplaceapi.md).
+This page describes the Plugins Directory API, not [Moodle Marketplace APIs](../moodlemarketplaceapi.mdx).
 
 For current Moodle Marketplace documentation, see [Moodle Marketplace documentation](https://moodle.atlassian.net/wiki/external/YTI4MmY4MWU2MDQyNDk5MTllZWY4YTBiNjA5ZDRjNWY).
 

package.json

@@ -36,7 +36,9 @@
     "@docusaurus/faster": "^3.10.2",
     "@docusaurus/plugin-pwa": "^3.10.2",
     "@docusaurus/preset-classic": "^3.10.2",
+    "@docusaurus/theme-common": "^3.10.2",
     "@docusaurus/theme-mermaid": "^3.10.2",
+    "@docusaurus/utils": "^3.10.2",
     "@emotion/react": "^11.10.5",
     "@emotion/styled": "^11.10.5",
     "@mdx-js/react": "^3.0.0",
@@ -58,6 +60,7 @@
     "react": "19",
     "react-dom": "19",
     "react-player": "^2.16.0",
+    "redocusaurus": "^2.5.2",
     "unist-util-find": "^3.0.0",
     "unist-util-visit": "^5.0.0"
   },

src/css/custom.css

@@ -143,6 +143,9 @@ html {
   footer.theme-doc-footer .theme-doc-footer-edit-meta-row {
     position: sticky;
     bottom: 0;
+
+    /* Stay above positioned page content, such as the Redoc API reference. */
+    z-index: 2;
     background-color: var(--ifm-background-color);
     margin-top: 0.5rem;
     padding-top: 0.5rem;
@@ -170,3 +173,13 @@ ul ol {
 .roadmap-table table tbody tr:nth-child(3) { background-color: #fef7c8; }
 .roadmap-table table tbody tr:nth-child(4) { background-color: #ffeceb; }
 .roadmap-table table tbody tr:nth-child(5) { background-color: #f8eefe; }
+
+/* Show the Redoc menu on the right, like the table of contents on other pages. */
+.redocusaurus .redoc-wrap {
+  flex-direction: row-reverse;
+}
+
+.redocusaurus .menu-content {
+  border-right: none;
+  border-left: 1px solid var(--ifm-toc-border-color);
+}