feat: better openapi docs

.github/workflows/docs.yaml

@@ -18,16 +18,20 @@ jobs:
 
         steps:
             -   uses: actions/checkout@v4
-            -   name: Use Node.js 20
+            -   name: Use Node.js 22
                 uses: actions/setup-node@v4
                 with:
-                    node-version: 20
+                    node-version: 22
                     cache: 'npm'
                     cache-dependency-path: 'package-lock.json'
                     always-auth: 'true'
                     registry-url: 'https://npm.pkg.github.com/'
                     scope: '@apify-packages'
 
+            - name: Enable corepack
+              run: |
+                  corepack enable
+
             -   name: Build docs
                 run: |
                     npm ci --force

.github/workflows/test.yaml

@@ -13,16 +13,20 @@ jobs:
             -   name: Checkout Source code
                 uses: actions/checkout@v4
 
-            -   name: Use Node.js 20
+            -   name: Use Node.js 22
                 uses: actions/setup-node@v4
                 with:
-                    node-version: 20
+                    node-version: 22
                     cache: 'npm'
                     cache-dependency-path: 'package-lock.json'
                     always-auth: 'true'
                     registry-url: 'https://npm.pkg.github.com/'
                     scope: '@apify-packages'
 
+            -   name: Enable corepack
+                run: |
+                    corepack enable
+
             -   name: Install Dependencies
                 run: npm ci --force
                 env:
@@ -36,40 +40,43 @@ jobs:
         name: Lint markdown content
         runs-on: ubuntu-latest
         steps:
-            - name: Checkout Source code
-              uses: actions/checkout@v4
-
-            - name: Get changed files
-              id: changed-files
-              uses: tj-actions/changed-files@v45
-              with:
-                files: |
-                    **/*.md
-                    **/*.mdx
-                separator: ","
-
-            - name: Use Node.js 20
-              uses: actions/setup-node@v4
-              with:
-                node-version: 20
-                cache: 'npm'
-                cache-dependency-path: 'package-lock.json'
-                registry-url: 'https://npm.pkg.github.com/'
-                scope: '@apify-packages'
-
-            - name: Install Dependencies
-              run: npm ci --force
-              env:
-                NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-            - name: List and Lint Changed Markdown Files
-              env:
-                ALL_CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
-              run: |
-                IFS=',' read -ra FILE_ARRAY <<< "$ALL_CHANGED_FILES"
-                for file in "${FILE_ARRAY[@]}"; do
-                  npx markdownlint "$file"
-                done
+            -   name: Checkout Source code
+                uses: actions/checkout@v4
+
+            -   name: Get changed files
+                id: changed-files
+                uses: tj-actions/changed-files@v45
+                with:
+                    files: '**/*.{md,mdx}'
+                    files_ignore: '!sources/api/*.{md,mdx}'
+                    separator: ","
+
+            -   name: Use Node.js 22
+                uses: actions/setup-node@v4
+                with:
+                    node-version: 22
+                    cache: 'npm'
+                    cache-dependency-path: 'package-lock.json'
+                    registry-url: 'https://npm.pkg.github.com/'
+                    scope: '@apify-packages'
+
+            -   name: Enable corepack
+                run: |
+                    corepack enable
+
+            -   name: Install Dependencies
+                run: npm ci --force
+                env:
+                    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+            -   name: List and Lint Changed Markdown Files
+                env:
+                    ALL_CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
+                run: |
+                    IFS=',' read -ra FILE_ARRAY <<< "$ALL_CHANGED_FILES"
+                    for file in "${FILE_ARRAY[@]}"; do
+                      npx markdownlint "$file"
+                    done
 
 
     lint_code:
@@ -79,15 +86,19 @@ jobs:
             -   name: Checkout Source code
                 uses: actions/checkout@v4
 
-            -   name: Use Node.js 20
+            -   name: Use Node.js 22
                 uses: actions/setup-node@v4
                 with:
-                    node-version: 20
+                    node-version: 22
                     cache: 'npm'
                     cache-dependency-path: 'package-lock.json'
                     registry-url: 'https://npm.pkg.github.com/'
                     scope: '@apify-packages'
 
+            -   name: Enable corepack
+                run: |
+                    corepack enable
+
             -   name: Install Dependencies
                 run: npm ci --force
                 env:

.github/workflows/typos-check.yaml

@@ -2,17 +2,17 @@ name: Typos Check
 
 on:
     pull_request:
-        branches: [master]
+        branches: [ master ]
 
 jobs:
     run:
         name: Spell Check with Typos
         runs-on: ubuntu-latest
         steps:
-            - name: Checkout code
-              uses: actions/checkout@v4
+            -   name: Checkout code
+                uses: actions/checkout@v4
 
-            - name: Check spelling
-              uses: crate-ci/typos@master
-              with:
-                  files: ./sources
+            -   name: Check spelling
+                uses: crate-ci/typos@master
+                with:
+                    files: ./sources

.github/workflows/vale.yaml

@@ -1,29 +1,29 @@
 name: Vale
 
-on: [pull_request]
+on: [ pull_request ]
 
 jobs:
-  lint:
-    runs-on: ubuntu-latest
+    lint:
+        runs-on: ubuntu-latest
 
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
+        steps:
+            -   uses: actions/checkout@v4
+                with:
+                    fetch-depth: 0
 
-      - name: Get changed files
-        id: changed-files
-        uses: tj-actions/changed-files@v45
-        with:
-          files: |
-            **/*.{md,mdx}
-          separator: ","
+            -   name: Get changed files
+                id: changed-files
+                uses: tj-actions/changed-files@v45
+                with:
+                    files: '**/*.{md,mdx}'
+                    files_ignore: '!sources/api/*.{md,mdx}'
+                    separator: ","
 
-      - uses: errata-ai/vale-action@reviewdog
-        if: steps.changed-files.outputs.any_changed == 'true'
-        with:
-          files: ${{ steps.changed-files.outputs.all_changed_files }}
-          separator: ","
-          fail_on_error: true
-          vale_flags: "--minAlertLevel=error"
-          reporter: github-pr-annotations
+            -   uses: errata-ai/vale-action@reviewdog
+                if: steps.changed-files.outputs.any_changed == 'true'
+                with:
+                    files: ${{ steps.changed-files.outputs.all_changed_files }}
+                    separator: ","
+                    fail_on_error: true
+                    vale_flags: "--minAlertLevel=error"
+                    reporter: github-pr-annotations

.gitignore

@@ -17,10 +17,7 @@ yarn.lock
 tmp
 jsconfig.json
 types
-sources/api
-sources/typedefs
 .history
 .docusaurus
 tsconfig.tsbuildinfo
 .turbo
-apify-docs-theme/package-lock.json

_typos.toml

@@ -7,3 +7,6 @@ extend-ignore-re = [
 
 [default.extend-words]
 SER = "SER"
+
+[files]
+extend-exclude = ['sources/api/*.mdx']

apify-docs-theme/package.json

@@ -20,7 +20,7 @@
     },
     "dependencies": {
         "@apify/docs-search-modal": "^1.1.1",
-        "@docusaurus/theme-common": "^3.5.2",
+        "@docusaurus/theme-common": "3.6.2",
         "@stackql/docusaurus-plugin-hubspot": "^1.1.0",
         "axios": "^1.7.4",
         "babel-loader": "^9.1.3",

apify-docs-theme/src/theme/Layout/index.jsx

@@ -2,12 +2,17 @@ import React from 'react';
 // cannot use any of the theme aliases here as it causes a circular dependency :( ideas welcome
 import Layout from '@docusaurus/theme-classic/lib/theme/Layout/index';
 import { usePluginData } from '@docusaurus/useGlobalData';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import { useLocation } from '@docusaurus/router';
 
 export default function LayoutWrapper(props) {
     const { options: { subNavbar } } = usePluginData('@apify/docs-theme');
+    const baseUrl = useBaseUrl('/');
+    const currentPath = useLocation().pathname.replace(new RegExp(`^${baseUrl}`), '');
+
     return (
         <div style={{
-            '--ifm-navbar-height': subNavbar ? '123px' : '68px',
+            '--ifm-navbar-height': subNavbar && !currentPath.startsWith('api/v2') ? '123px' : '68px',
             'margin': 0,
             'padding': 0,
             'boxSizing': 'border-box',

apify-docs-theme/src/theme/custom.css

@@ -1619,3 +1619,59 @@ iframe[src*="youtube"] {
     margin-top: -130px;
     position: absolute;
 }
+
+.redocusaurus .openapi-clients-box {
+    display: block;
+    float: right;
+    padding-left: 6px;
+}
+
+.redocusaurus .openapi-clients-box-heading {
+    display: inline-block;
+    font-family: 'San Francisco', Helvetica, Arial, sans-serif;
+    color: #6C7590;
+    font-style: normal;
+    font-weight: 700;
+    font-size: 14px;
+    line-height: 20px;
+    text-transform: uppercase;
+    padding-bottom: 6px;
+}
+
+.redocusaurus .openapi-clients-box-icon {
+    display: block;
+    padding-bottom: 6px;
+}
+
+.theme-api-markdown .openapi-clients-box {
+    display: block;
+    float: right;
+    padding-left: 6px;
+}
+
+.theme-api-markdown .openapi-clients-box-heading {
+    display: inline-block;
+    font-family: 'San Francisco', Helvetica, Arial, sans-serif;
+    color: #6C7590;
+    font-style: normal;
+    font-weight: 700;
+    font-size: 14px;
+    line-height: 20px;
+    text-transform: uppercase;
+    padding-bottom: 6px;
+}
+
+.theme-api-markdown .openapi-clients-box-icon {
+    display: block;
+    padding-bottom: 6px;
+    margin: 0 !important;
+}
+
+.theme-api-markdown .openapi__method-endpoint-path,
+.theme-api-markdown .openapi-security__summary-header {
+    margin-top: 0;
+}
+
+.theme-api-markdown .prism-code .token-line::before {
+    display: none !important;
+}

babel.config.js

@@ -1,4 +1,4 @@
 module.exports = {
-    presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+    presets: ['@docusaurus/babel/preset'],
     plugins: ['babel-plugin-styled-components'],
 };