add plugin to find floating pages

Author: Blargian

docusaurus.config.en.js

@@ -4,7 +4,8 @@ import katex from "rehype-katex";
 import chHeader from "./plugins/header.js";
 import fixLinks from "./src/hooks/fixLinks.js";
 const { customParseFrontMatter } = require('./plugins/frontmatter-validation/customParseFrontMatter');
-
+const checkFloatingPages = require('./plugins/checkFloatingPages');
+const frontmatterValidator = require('./plugins/frontmatter-validation/frontmatterValidatorPlugin');
 // Helper function to skip over index.md files.
 function skipIndex(items) {
   return items.filter(({ type, id }) => {
@@ -317,13 +318,25 @@ const config = {
       },
     ],
     chHeader,
-    './plugins/frontmatter-validation/frontmatterValidatorPlugin'
+    [
+      frontmatterValidator,
+      {
+        failBuild: true,
+      },
+    ],
+    [
+        checkFloatingPages,
+        {
+          failBuild: true,
+        },
+    ]
   ],
   customFields: {
     blogSidebarLink: "/docs/knowledgebase", // Used for KB article page
     galaxyApiEndpoint:
       process.env.NEXT_PUBLIC_GALAXY_API_ENDPOINT || "http://localhost:3000",
   },
+
 };
 
 module.exports = config;

plugins/checkFloatingPages.js

@@ -13,11 +13,14 @@ async function checkFloatingPages(context, options) {
             const docsDir = path.resolve(context.siteDir, 'docs');
 
             let sidebarItems = [];
+            let autogeneratedDirs = [];
             const sidebarsPath = path.join(context.siteDir, 'sidebars.js');
             if (fs.existsSync(sidebarsPath)) {
                 try {
                     const sidebars = require(sidebarsPath);
-                    sidebarItems = getSidebarItems(sidebars);
+                    const result = getSidebarItemsAndAutogenerated(context, sidebars);
+                    sidebarItems = result.items;
+                    autogeneratedDirs = result.autogeneratedDirs;
                 } catch (err) {
                     console.error("Error loading sidebars.js", err);
                     throw err; // Stop the build
@@ -28,58 +31,173 @@ async function checkFloatingPages(context, options) {
             const floatingPages = [];
 
             for (const filePath of markdownFiles) {
+                // directories to skip
+                if (filePath.includes('_'))
+                    continue;
+
                 const fileContent = fs.readFileSync(filePath, 'utf-8');
                 const { data } = matter(fileContent);
 
                 const relativePath = path.relative(docsDir, filePath).replace(/\\/g, '/').replace(/\.md$/, '');
 
-                // Check 1: Explicit sidebar_position or id in frontmatter
-                if (data.sidebar_position || data.id) {
-                    const idToCheck = data.id || relativePath;
-                    if (!sidebarItems.includes(idToCheck)) {
-                        floatingPages.push(filePath);
-                    }
-                } else {
-                    //Check 2: Implicit.
-                    if (!sidebarItems.includes(relativePath)) {
-                        floatingPages.push(filePath);
-                    }
+                // Skip if the document has sidebar: false explicitly set
+                if (data.sidebar === false) {
+                    continue;
+                }
+
+                const idToCheck = data.id || relativePath;
+
+                // Check various ways this document could be included in the sidebar
+                if (isDocumentIncluded(idToCheck, relativePath, sidebarItems, autogeneratedDirs)) {
+                    continue;
                 }
+
+                floatingPages.push(filePath);
             }
 
             if (floatingPages.length > 0) {
-                console.error('\x1b[31m%s\x1b[0m', 'Floating pages found:');
-                floatingPages.forEach(page => console.error(`  - ${page}`));
                 if (options && options.failBuild) {
-                    throw new Error('Floating pages found. See above for details.');
+                    console.error('\x1b[31m%s\x1b[0m', `${floatingPages.length} floating pages found:`);
+                    floatingPages.forEach(page => console.error(`  - ${page}`));
+                    throw new Error('🚨 Floating pages found. See above for details.');
+                } else {
+                    console.log('⚠️', 'Found floating pages:');
+                    floatingPages.forEach(page => console.log(`  - ${page}`));
                 }
             } else {
-                console.log('\x1b[32m%s\x1b[0m', 'No floating pages found.');
+                console.log('✅', 'No floating pages found.');
             }
         }
     }
 }
 
-function getSidebarItems(sidebarConfig) {
-    let items = []
+// Helper function to check if a document is included in sidebar or autogenerated directories
+function isDocumentIncluded(idToCheck, relativePath, sidebarItems, autogeneratedDirs) {
+    // Direct check if ID is in sidebar items
+    if (sidebarItems.includes(idToCheck)) {
+        return true;
+    }
+
+    // Check variations for index pages
+    if (relativePath.endsWith('/index')) {
+        const parentDir = relativePath.replace(/\/index$/, '');
+        if (sidebarItems.includes(parentDir)) {
+            return true;
+        }
+    }
+
+    // Check if any sidebar item is a string and matches the ID without the /index
+    for (const item of sidebarItems) {
+        if (typeof item === 'string') {
+            // If the item directly matches
+            if (item === idToCheck) {
+                return true;
+            }
+
+            // For index pages, check if the parent directory matches
+            if (relativePath.endsWith('/index') && item === relativePath.replace(/\/index$/, '')) {
+                return true;
+            }
+        } else if (typeof item === 'object' && item !== null) {
+            // Handle link items
+            if (item.type === 'link' && item.href) {
+                const href = item.href;
+                // Extract the path from the href
+                let linkPath = href.replace(/^\/docs\//, '').replace(/\/$/, '');
+
+                // Check if this link points to the current document
+                if (linkPath === idToCheck ||
+                    linkPath === relativePath ||
+                    (relativePath.endsWith('/index') && linkPath === relativePath.replace(/\/index$/, ''))) {
+                    return true;
+                }
+            }
+        }
+    }
+
+    // Check if document is in an autogenerated directory
+    for (const dir of autogeneratedDirs) {
+        // Direct check
+        if (relativePath.startsWith(dir + '/') || relativePath === dir) {
+            return true;
+        }
+
+        // Handle index files specifically
+        if (relativePath === `${dir}/index`) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+function getSidebarItemsAndAutogenerated(context, sidebarConfig) {
+    let items = [];
+    let autogeneratedDirs = [];
+
     function traverse(item) {
         if (item.type === 'doc') {
             items.push(item.id);
-        } else if (item.type === 'category' || item.type === 'autogenerated') {
+        } else if (item.type === 'category') {
+            // Add the category link itself if it has a link
+            if (item.link && item.link.type === 'doc' && item.link.id) {
+                items.push(item.link.id);
+            }
+
+            // Process all items in the category
             (item.items || []).forEach(traverse);
+        } else if (item.type === 'autogenerated') {
+            const dirPath = item.dirName;
+            let dir;
+
+            // Handle both absolute and relative paths
+            if (path.isAbsolute(dirPath)) {
+                dir = path.relative(path.resolve(context.siteDir, 'docs'), dirPath);
+            } else {
+                dir = dirPath;
+            }
+
+            dir = dir.replace(/\\/g, '/');
+
+            // Remove leading 'docs/' if present
+            dir = dir.replace(/^docs\//, '');
+
+            // Remove trailing slash if present
+            dir = dir.replace(/\/$/, '');
+
+            autogeneratedDirs.push(dir);
         } else if (item.type === 'link') {
-            // no need to worry about links
+            // Add the link item directly to check later
+            items.push(item);
+
+            // Check if the link is to a local doc
+            const href = item.href || '';
+            if (href.startsWith('/') && !href.startsWith('//')) {
+                // Extract doc ID from local path
+                const docPath = href.replace(/^\/docs\//, '').replace(/\/$/, '');
+                if (docPath) {
+                    items.push(docPath);
+                }
+            }
+        } else if (typeof item === 'string') {
+            items.push(item);
         }
     }
-    // sidebarConfig can be an array or an object
-    if (Array.isArray(sidebarConfig)) {
-        sidebarConfig.forEach(traverse);
-    } else {
-        Object.values(sidebarConfig).forEach(sidebar => {
-            sidebar.forEach(traverse)
-        })
+
+    const cleanedSidebarConfig = { ...sidebarConfig };
+    // we don't check top level nav
+    if (cleanedSidebarConfig.dropdownCategories) {
+        delete cleanedSidebarConfig.dropdownCategories;
     }
-    return items;
+
+    Object.values(cleanedSidebarConfig).forEach(sidebar => {
+        sidebar.forEach(traverse);
+    });
+
+    return {
+        items,
+        autogeneratedDirs
+    };
 }
 
 module.exports = checkFloatingPages;