Fix doc headers on sub-pages (#35683)

docusaurus/src/remark/docsHeaderDecoration.js

@@ -10,7 +10,8 @@ const toAttributes = (props) =>
 
 const plugin = () => {
   const transformer = async (ast, vfile) => {
-    if (!isDocsPage(vfile)) return;
+    const docsPageInfo = isDocsPage(vfile);
+    if (!docsPageInfo.isDocsPage) return;
 
     const registryEntry = await getRegistryEntry(vfile);
 

docusaurus/src/remark/specDecoration.js

@@ -15,19 +15,30 @@ async function injectSpecSchema(ast) {
   visit(ast, "mdxJsxFlowElement", (node) => {
     if (node.name !== "SpecSchema" && node.name !== "AirbyteLibExample") return;
 
-    const connectorName = node.attributes.find((attr) => attr.name === "connector").value;
-    const connectorSpec = registry.find((c) => c.dockerRepository_oss === `airbyte/${connectorName}`).spec_oss.connectionSpecification;
+    const connectorName = node.attributes.find(
+      (attr) => attr.name === "connector"
+    ).value;
+    const connectorSpec = registry.find(
+      (c) => c.dockerRepository_oss === `airbyte/${connectorName}`
+    ).spec_oss.connectionSpecification;
     node.attributes.push({
       type: "mdxJsxAttribute",
       name: "specJSON",
-      value: JSON.stringify(connectorSpec)
+      value: JSON.stringify(connectorSpec),
     });
   });
 }
 
 async function injectDefaultAirbyteLibSection(vfile, ast) {
   const registryEntry = await getRegistryEntry(vfile);
-  if (!isDocsPage(vfile) || !registryEntry || !isPypiConnector(registryEntry) || vfile.value.includes("## Usage with airbyte-lib")) {
+  const docsPageInfo = isDocsPage(vfile);
+
+  if (
+    !docsPageInfo.isTrueDocsPage ||
+    !registryEntry ||
+    !isPypiConnector(registryEntry) ||
+    vfile.value.includes("## Usage with airbyte-lib")
+  ) {
     return;
   }
   const connectorName = registryEntry.dockerRepository_oss.split("/").pop();
@@ -36,31 +47,41 @@ async function injectDefaultAirbyteLibSection(vfile, ast) {
   visit(ast, "heading", (node, index, parent) => {
     if (!added && isChangelogHeading(node)) {
       added = true;
-      parent.children.splice(index, 0, {
-        type: "heading",
-        depth: 2,
-        children: [{ type: "text", value: "Reference" }]
-      }, {
-        type: "mdxJsxFlowElement",
-        name: "SpecSchema",
-        attributes: [
-          {
-            type: "mdxJsxAttribute",
-            name: "connector",
-            value: connectorName
-          },
-        ]
-      });
+      parent.children.splice(
+        index,
+        0,
+        {
+          type: "heading",
+          depth: 2,
+          children: [{ type: "text", value: "Reference" }],
+        },
+        {
+          type: "mdxJsxFlowElement",
+          name: "SpecSchema",
+          attributes: [
+            {
+              type: "mdxJsxAttribute",
+              name: "connector",
+              value: connectorName,
+            },
+          ],
+        }
+      );
     }
   });
   if (!added) {
-    throw new Error(`Could not find a changelog heading in ${vfile.path} to add the default airbyte-lib section. This connector won't have a reference section. Make sure there is either a ## Changelog section or add a manual reference section.`);
+    throw new Error(
+      `Could not find a changelog heading in ${vfile.path} to add the default airbyte-lib section. This connector won't have a reference section. Make sure there is either a ## Changelog section or add a manual reference section.`
+    );
   }
 }
 
 function isChangelogHeading(node) {
-  return node.depth === 2 && node.children.length === 1 && node.children[0].value.toLowerCase() === "changelog";
+  return (
+    node.depth === 2 &&
+    node.children.length === 1 &&
+    node.children[0].value.toLowerCase() === "changelog"
+  );
 }
 
-
 module.exports = plugin;

docusaurus/src/remark/utils.js

@@ -1,29 +1,53 @@
 const { catalog } = require("../connector_registry");
 
+// the migration guide and troubleshooting guide are not connectors, but also not in a sub-folder, e.g. /integrations/sources/mssql-migrations
+const connectorPageAlternativeEndings = ["-migrations", "-troubleshooting"];
+const connectorPageAlternativeEndingsRegExp = new RegExp(
+  connectorPageAlternativeEndings.join("|"),
+  "gi"
+);
+
 const isDocsPage = (vfile) => {
+  let response = { isDocsPage: false, isTrueDocsPage: false };
+
+  if (
+    vfile.path.includes("integrations/sources") ||
+    vfile.path.includes("integrations/destinations")
+  ) {
+    response.isDocsPage = true;
+    response.isTrueDocsPage = true;
+  }
+
+  if (response.isDocsPage === true) {
+    for (const ending of connectorPageAlternativeEndings) {
+      if (vfile.path.includes(ending)) {
+        response.isTrueDocsPage = false;
+      }
+    }
+  }
+
+  return response;
+};
+
+const getRegistryEntry = async (vfile) => {
   if (
     !vfile.path.includes("integrations/sources") &&
     !vfile.path.includes("integrations/destinations")
   ) {
-    return false;
+    return;
   }
 
-  // skip the root files in integrations/source and integrations/destinations
-  if (vfile.path.includes("README.md")) {
-    return false;
-  }
-
-  if (vfile.path.includes("-migrations.md")) {
-    return false;
-  }
-
-  return true;
-};
-
-const getRegistryEntry = async (vfile) => {
+  // troubleshooting pages are sub-pages, but migration pages are not?
+  // ["sources", "mysql"] vs ["sources", "mysql", "troubleshooting"] vs ["sources", "mysql-migrations"]
   const pathParts = vfile.path.split("/");
-  const connectorName = pathParts.pop().split(".")[0];
-  const connectorType = pathParts.pop();
+  while (pathParts[0] !== "integrations") pathParts.shift();
+  pathParts.shift();
+  const connectorType = pathParts.shift();
+  const connectorName = pathParts
+    .shift()
+    .split(".")[0]
+    .replace(connectorPageAlternativeEndingsRegExp, "");
+
   const dockerRepository = `airbyte/${connectorType.replace(
     /s$/,
     ""