Organize API navigation across docs

.github/scripts/i18n/sync-docs-json.mjs

@@ -118,8 +118,14 @@ export function normalizeNavTree(nodes, options = {}) {
     }
     if (node && typeof node === "object" && Array.isArray(node.pages)) {
       const pages = normalizeNavTree(node.pages, options);
-      if (pages.length === 0 && pruneMissing) continue;
+      if (pages.length === 0 && pruneMissing && node.openapi == null) continue;
       out.push({ ...node, pages });
+      continue;
+    }
+    // OpenAPI-only groups have `openapi` and no `pages`; dropping them
+    // removes the API reference from the sidebar.
+    if (node && typeof node === "object" && node.openapi != null) {
+      out.push(node);
     }
   }
   return out;
@@ -156,11 +162,15 @@ export function localizeNavTree(nodes, langDir, langDirs) {
     if (typeof node === "string") {
       return localizePagePath(node, langDir, langDirs);
     }
-    if (node && typeof node === "object" && Array.isArray(node.pages)) {
-      return {
-        ...node,
-        pages: localizeNavTree(node.pages, langDir, langDirs),
-      };
+    if (node && typeof node === "object") {
+      const next = { ...node };
+      if (node.openapi != null) {
+        next.openapi = localizeOpenApi(node.openapi, langDir);
+      }
+      if (Array.isArray(node.pages)) {
+        next.pages = localizeNavTree(node.pages, langDir, langDirs);
+      }
+      return next;
     }
     return node;
   });
@@ -242,15 +252,42 @@ function findGroupMatch(existingPages, newChild, langDirs) {
   return best;
 }
 
+/** @param {unknown} openapi @returns {string | null} */
+export function openApiSourceKey(openapi) {
+  if (typeof openapi === "string") return openapi;
+  if (openapi && typeof openapi === "object" && typeof openapi.source === "string") {
+    return openapi.source;
+  }
+  return null;
+}
+
 /**
- * @param {unknown[]} newPages
  * @param {unknown[]} existingPages
- * @param {string[]} langDirs
+ * @param {object} newChild
  */
+function findOpenApiMatch(existingPages, newChild) {
+  const source = openApiSourceKey(newChild?.openapi);
+  if (!source || !Array.isArray(existingPages)) return null;
+  return (
+    existingPages.find(
+      (node) =>
+        node && typeof node === "object" && openApiSourceKey(node.openapi) === source
+    ) ?? null
+  );
+}
+
 export function mergeNavPages(newPages, existingPages, langDirs) {
   if (!Array.isArray(newPages)) return [];
   return newPages.map((newChild) => {
     if (typeof newChild === "string") return newChild;
+    if (newChild?.openapi != null && !Array.isArray(newChild.pages)) {
+      const match = findOpenApiMatch(existingPages, newChild);
+      if (!match) return newChild;
+      const merged = { ...newChild };
+      if (match.group) merged.group = match.group;
+      if (match.icon) merged.icon = match.icon;
+      return merged;
+    }
     if (!newChild?.pages) return newChild;
 
     const match = findGroupMatch(existingPages, newChild, langDirs);

custom-nodes/intro.mdx

@@ -0,0 +1,23 @@
+---
+title: "Custom Nodes"
+sidebarTitle: "Overview"
+description: "Choose the right path for building, extending, and publishing ComfyUI custom nodes."
+---
+
+Custom Nodes extend ComfyUI with new server-side behavior, user-interface features, and integrations. Choose a path based on what you are trying to do.
+
+<CardGroup cols={2}>
+  <Card title="Build Custom Nodes" icon="code" href="/custom-nodes/overview">
+    Learn the client-server model, node categories, Python backend, and JavaScript frontend before building your node.
+  </Card>
+  <Card title="Package & Publish" icon="box" href="/registry/overview">
+    Prepare a node package, publish it to the Comfy Registry, and manage versions and releases.
+  </Card>
+</CardGroup>
+
+## Choose a starting point
+
+- **New to custom nodes:** start with [Custom Nodes Overview](/custom-nodes/overview).
+- **Building the backend:** see [Python (Backend)](/custom-nodes/backend/server_overview).
+- **Extending the UI:** see [JavaScript (UI)](/custom-nodes/js/javascript_overview).
+- **Publishing a package:** start with the [Registry Overview](/registry/overview).

development/api-development/sdks.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Comfy SDKs"
 description: "Official Python and TypeScript SDKs for running ComfyUI workflows from your own application"
-sidebarTitle: "Overview"
+sidebarTitle: "SDK Overview"
 icon: "code"
 ---
 

development/overview.mdx

@@ -55,39 +55,10 @@ Manage your ComfyUI installation, custom nodes, and workflows from the command l
 
 See also: [CLI Reference](/comfy-cli/reference) · [Troubleshooting](/comfy-cli/troubleshooting)
 
-## Develop Custom Nodes
+## Custom Nodes
 
-Custom nodes let you extend ComfyUI with your own Python backends, JavaScript UI widgets, and integrations. This is one of the most powerful ways to contribute to the ecosystem.
-
-<CardGroup cols={2}>
-  <Card title="Getting Started" icon="compass" href="/custom-nodes/overview">
-    New to custom nodes? Learn the anatomy of a node, how to publish it, and best practices.
-    <br /><br />
-    Key pages: <a href="/custom-nodes/walkthrough">Walkthrough</a> · <a href="/custom-nodes/v3_migration">v3 Migration Guide</a>
-  </Card>
-
-  <Card title="Backend (Python)" icon="python" href="/custom-nodes/backend/server_overview">
-    Build the server-side of your custom node. Covers data types, image &amp; mask handling, lazy evaluation, tensors, and more.
-    <br /><br />
-    Key pages: <a href="/custom-nodes/backend/datatypes">Data Types</a> · <a href="/custom-nodes/backend/images_and_masks">Images &amp; Masks</a> · <a href="/custom-nodes/backend/lazy_evaluation">Lazy Evaluation</a> · <a href="/custom-nodes/backend/expansion">Node Expansion</a>
-  </Card>
-
-  <Card title="Frontend (JavaScript)" icon="js" href="/custom-nodes/js/javascript_overview">
-    Add custom UI widgets, sidebar tabs, keybindings, and dialogs to your nodes. Full control over the ComfyUI frontend.
-    <br /><br />
-    Key pages: <a href="/custom-nodes/js/javascript_hooks">Hooks</a> · <a href="/custom-nodes/js/javascript_sidebar_tabs">Sidebar Tabs</a> · <a href="/custom-nodes/js/javascript_commands_keybindings">Commands &amp; Keybindings</a> · <a href="/custom-nodes/js/javascript_examples">Examples</a>
-  </Card>
-
-</CardGroup>
-
-See also: <a href="/custom-nodes/i18n">Internationalization (i18n)</a>
+Extend ComfyUI with Python backends, JavaScript UI extensions, and integrations. Start with the [Custom Nodes overview](/custom-nodes/overview).
 
 ## Registry
 
-Publish and manage your custom nodes through the Comfy Registry. The Registry provides versioning, security scanning, and discovery for the community.
-
-<Card title="Publishing Overview" icon="puzzle-piece" href="/registry/overview">
-  Register as a publisher, publish your first node, claim existing ones, and set up CI/CD for automated releases.
-</Card>
-
-See also: [Publishing Tutorial](/registry/publishing) · [Standards](/registry/standards) · [CI/CD](/registry/cicd) · [Specifications](/registry/specifications)
+Package and publish custom nodes through the Comfy Registry. Start with the [Registry overview](/registry/overview) or the [publishing tutorial](/registry/publishing).