fix: make TOC rendering consistent regardless of the page content

apify-docs-theme/package.json

@@ -19,7 +19,7 @@
         "access": "public"
     },
     "dependencies": {
-        "@apify/docs-search-modal": "^1.1.0",
+        "@apify/docs-search-modal": "^1.1.1",
         "@docusaurus/theme-common": "^3.5.2",
         "@stackql/docusaurus-plugin-hubspot": "^1.1.0",
         "axios": "^1.7.4",

apify-docs-theme/src/theme/TOCItems/Tree.jsx

@@ -0,0 +1,41 @@
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+import React from 'react';
+
+import styles from './styles.module.css';
+
+// Recursive component rendering the toc tree
+function TOCItemTree({
+    toc,
+    className,
+    linkClassName,
+    isChild,
+}) {
+    if (!toc.length) {
+        return null;
+    }
+    return (
+        <ul className={isChild ? undefined : className}>
+            {toc.map((heading) => (
+                <li key={heading.id}>
+                    <Link
+                        to={`#${heading.id}`}
+                        className={clsx(styles.apifyTocLink, linkClassName ?? undefined)}
+                        data-label={heading.value}
+                        // Developer provided the HTML, so assume it's safe.
+                        dangerouslySetInnerHTML={{ __html: heading.value }}
+                    />
+                    <TOCItemTree
+                        isChild
+                        toc={heading.children}
+                        className={className}
+                        linkClassName={linkClassName}
+                    />
+                </li>
+            ))}
+        </ul>
+    );
+}
+
+// Memo only the tree root is enough
+export default React.memo(TOCItemTree);

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

@@ -0,0 +1,50 @@
+import { useThemeConfig } from '@docusaurus/theme-common';
+import {
+    useTOCHighlight,
+    useFilteredAndTreeifiedTOC,
+} from '@docusaurus/theme-common/internal';
+import TOCItemTree from '@theme/TOCItems/Tree';
+import React, { useMemo } from 'react';
+
+export default function TOCItems({
+    toc,
+    className = 'table-of-contents table-of-contents__left-border',
+    linkClassName = 'table-of-contents__link',
+    linkActiveClassName = undefined,
+    minHeadingLevel: minHeadingLevelOption,
+    maxHeadingLevel: maxHeadingLevelOption,
+    ...props
+}) {
+    const themeConfig = useThemeConfig();
+
+    const minHeadingLevel = minHeadingLevelOption ?? themeConfig.tableOfContents.minHeadingLevel;
+    const maxHeadingLevel = maxHeadingLevelOption ?? themeConfig.tableOfContents.maxHeadingLevel;
+
+    const tocTree = useFilteredAndTreeifiedTOC({
+        toc,
+        minHeadingLevel,
+        maxHeadingLevel,
+    });
+
+    const tocHighlightConfig = useMemo(() => {
+        if (linkClassName && linkActiveClassName) {
+            return {
+                linkClassName,
+                linkActiveClassName,
+                minHeadingLevel,
+                maxHeadingLevel,
+            };
+        }
+        return undefined;
+    }, [linkClassName, linkActiveClassName, minHeadingLevel, maxHeadingLevel]);
+    useTOCHighlight(tocHighlightConfig);
+
+    return (
+        <TOCItemTree
+            toc={tocTree}
+            className={className}
+            linkClassName={linkClassName}
+            {...props}
+        />
+    );
+}

apify-docs-theme/src/theme/TOCItems/styles.module.css

@@ -0,0 +1,12 @@
+.apifyTocLink {
+    display: block;
+}
+
+.apifyTocLink::before {
+    display: block;
+    content: attr(data-label);
+    font-weight: 700;
+    height: 0;
+    overflow: hidden;
+    visibility: hidden;
+}

src/theme/DocItem/Layout/index.js

@@ -74,7 +74,7 @@ export default function DocItemLayout({ children }) {
     );
     return (
         <div
-            className="row">
+            className={clsx('row', styles.row)}>
             <div
                 className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
                 <DocVersionBanner/>

src/theme/DocItem/Layout/styles.module.css

@@ -21,4 +21,8 @@
   .docItemCol {
     max-width: 820px !important;
   }
-}
+}
+
+.row {
+  flex-wrap: nowrap;
+}