fix: openapi docs improvements (#1344)

- unify sidebar and content badges for method type (post/put/create/delete/...) - render category index pages - hide next/prev buttons from openapi docs pages - remove descriptions from generated category index of openapi docs - add missing syntax highlighting and use custom language order and labels - enable docusaurus 3.6 perf optimizations expect SWC loader (not working with styled components) --------- Co-authored-by: Michał Olender <[email protected]>
apify · Dec 12, 2024 · d0ae355 · d0ae355
1 parent d75b4e7
commit d0ae355
Show file tree

Hide file tree

Showing 7 changed files with 4,536 additions and 5,258 deletions.
diff --git a/apify-docs-theme/src/theme/custom.css b/apify-docs-theme/src/theme/custom.css
@@ -1709,57 +1709,86 @@ iframe[src*="youtube"] {
     top: -1.5px;
 }
 
-.get > .menu__link::before {
-    content: 'get';
+.theme-api-markdown .openapi__method-endpoint .badge {
+    border-inline-start-width: 5px;
+    padding: 3px 5px 3px 4px;
+    margin-right: 5px;
+}
+
+.get > .menu__link::before,
+.theme-api-markdown .openapi__method-endpoint .badge--primary {
     background-color: var(--ifm-color-info-contrast-background);
     color: var(--ifm-color-info-contrast-foreground);
     border-color: var(--ifm-color-info-dark);
 }
 
+.get > .menu__link::before {
+    content: 'get';
+}
+
 .post > .menu__link::before {
     content: 'post';
+}
+
+.post > .menu__link::before,
+.theme-api-markdown .openapi__method-endpoint .badge--success {
     background-color: var(--ifm-color-success-contrast-background);
     color: var(--ifm-color-success-contrast-foreground);
     border-color: var(--ifm-color-success-dark);
 }
 
 .delete > .menu__link::before {
     content: 'del';
+}
+
+.delete > .menu__link::before,
+.theme-api-markdown .openapi__method-endpoint .badge--danger {
     background-color: var(--ifm-color-danger-contrast-background);
     color: var(--ifm-color-danger-contrast-foreground);
     border-color: var(--ifm-color-danger-dark);
 }
 
 .put > .menu__link::before {
     content: 'put';
+}
+
+.put > .menu__link::before,
+.theme-api-markdown .openapi__method-endpoint .badge--info {
     background-color: var(--ifm-color-warning-contrast-background);
     color: var(--ifm-color-warning-contrast-foreground);
     border-color: var(--ifm-color-warning-dark);
 }
 
 .patch > .menu__link::before {
     content: 'patch';
+}
+
+.patch > .menu__link::before,
+.theme-api-markdown .openapi__method-endpoint .badge--warning {
     background-color: var(--ifm-color-success-contrast-background);
     color: var(--ifm-color-success-contrast-foreground);
     border-color: var(--ifm-color-success-dark);
 }
 
 .head > .menu__link::before {
     content: 'head';
+}
+
+.head > .menu__link::before,
+.event > .menu__link::before,
+.schema > .menu__link::before,
+.theme-api-markdown .openapi__method-endpoint .badge--secondary {
     background-color: var(--ifm-color-secondary-contrast-background);
     color: var(--ifm-color-secondary-contrast-foreground);
     border-color: var(--ifm-color-secondary-dark);
 }
 
 .event > .menu__link::before {
     content: 'event';
-    background-color: var(--ifm-color-secondary-contrast-background);
-    color: var(--ifm-color-secondary-contrast-foreground);
-    border-color: var(--ifm-color-secondary-dark);
 }
 
-.schema > .menu__link::before {
-    content: 'schema';
+.event > .menu__link::before,
+.theme-api-markdown .openapi__method-endpoint .badge--secondary {
     background-color: var(--ifm-color-secondary-contrast-background);
     color: var(--ifm-color-secondary-contrast-foreground);
     border-color: var(--ifm-color-secondary-dark);
@@ -1770,6 +1799,10 @@ iframe[src*="youtube"] {
     margin-bottom: calc(var(--ifm-h1-vertical-rhythm-bottom)* var(--ifm-leading)) !important;
 }
 
+.theme-doc-markdown .openapi-tabs__code-container .openapi-tabs__code-item span {
+    text-transform: none;
+}
+
 @media (max-width: 996px) {
     div[class^="navbarSearchContainer"] {
         position: static;

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -16,9 +16,16 @@ module.exports = {
     organizationName: 'apify',
     projectName: 'apify-docs',
     scripts: ['/js/custom.js'],
-    // future: {
-    //     experimental_faster: true,
-    // },
+    future: {
+        experimental_faster: {
+            // swcJsLoader: true,
+            swcJsMinimizer: true,
+            swcHtmlMinimizer: true,
+            lightningCssMinimizer: true,
+            rspackBundler: true,
+            mdxCrossCompilerCache: true,
+        },
+    },
     headTags: [
         {
             tagName: 'link',
@@ -190,11 +197,12 @@ module.exports = {
                         outputDir: './sources/api',
                         sidebarOptions: {
                             groupPathsBy: 'tag',
+                            categoryLinkSource: 'tag',
                             sidebarCollapsed: false,
                             sidebarCollapsible: false,
                             sidebarGenerators: {
                                 createDocItem: (item, context) => {
-                                    const legacyUrls = item.api['x-legacy-doc-urls'] ?? [];
+                                    const legacyUrls = item.api?.['x-legacy-doc-urls'] ?? [];
                                     const altIds = legacyUrls.map((url) => {
                                         const { hash } = new URL(url);
                                         return hash;
@@ -267,6 +275,11 @@ module.exports = {
         parseFrontMatter: async (params) => {
             const result = await params.defaultParseFrontMatter(params);
 
+            if (result.frontMatter.api || result.content.startsWith('<span class="openapi-clients-box">')) {
+                result.frontMatter.pagination_next = null;
+                result.frontMatter.pagination_prev = null;
+            }
+
             if (result.frontMatter.id === 'apify-api') {
                 result.frontMatter.slug = '/';
             }
@@ -282,7 +295,127 @@ module.exports = {
             return result;
         },
     },
-    themeConfig: config.themeConfig,
+    themeConfig: {
+        ...config.themeConfig,
+        prism: {
+            ...config.themeConfig.prism,
+            additionalLanguages: [
+                ...config.themeConfig.prism.additionalLanguages,
+                'http', 'bash', 'ruby', 'java', 'scala', 'go', 'csharp', 'powershell', 'dart', 'objectivec', 'ocaml', 'r',
+            ],
+        },
+        languageTabs: [
+            {
+                highlight: 'javascript',
+                label: 'JavaScript',
+                language: 'javascript',
+                logoClass: 'javascript',
+            },
+            {
+                highlight: 'python',
+                label: 'Python',
+                language: 'python',
+                logoClass: 'python',
+            },
+            {
+                highlight: 'bash',
+                label: 'cURL',
+                language: 'curl',
+                logoClass: 'curl',
+            },
+            {
+                highlight: 'php',
+                label: 'PHP',
+                language: 'php',
+                logoClass: 'php',
+            },
+            {
+                highlight: 'java',
+                label: 'Java',
+                language: 'java',
+                logoClass: 'java',
+                variant: 'unirest',
+            },
+            {
+                highlight: 'c',
+                label: 'C',
+                language: 'c',
+                logoClass: 'c',
+            },
+            {
+                highlight: 'csharp',
+                label: 'C#',
+                language: 'csharp',
+                logoClass: 'csharp',
+            },
+            {
+                highlight: 'go',
+                label: 'Go',
+                language: 'go',
+                logoClass: 'go',
+            },
+            {
+                highlight: 'rust',
+                label: 'Rust',
+                language: 'rust',
+                logoClass: 'rust',
+            },
+            {
+                highlight: 'javascript',
+                label: 'Node.js',
+                language: 'nodejs',
+                logoClass: 'nodejs',
+            },
+            {
+                highlight: 'ruby',
+                label: 'Ruby',
+                language: 'ruby',
+                logoClass: 'ruby',
+            },
+            {
+                highlight: 'powershell',
+                label: 'PowerShell',
+                language: 'powershell',
+                logoClass: 'powershell',
+            },
+            {
+                highlight: 'dart',
+                label: 'Dart',
+                language: 'dart',
+                logoClass: 'dart',
+            },
+            {
+                highlight: 'objectivec',
+                label: 'Objective-C',
+                language: 'objective-c',
+                logoClass: 'objective-c',
+            },
+            {
+                highlight: 'ocaml',
+                label: 'OCaml',
+                language: 'ocaml',
+                logoClass: 'ocaml',
+            },
+            {
+                highlight: 'r',
+                label: 'R',
+                language: 'r',
+                logoClass: 'r',
+            },
+            {
+                highlight: 'swift',
+                label: 'Swift',
+                language: 'swift',
+                logoClass: 'swift',
+            },
+            {
+                highlight: 'kotlin',
+                label: 'Kotlin',
+                language: 'kotlin',
+                logoClass: 'kotlin',
+            },
+        ],
+    },
     staticDirectories: ['apify-docs-theme/static', 'static'],
     customFields: {
         forbiddenGiscusDocRegExpStrings: [