Docusaurus Sidebar 計數功能的進階實作：遞迴統計與穩定 slug

/**
 * Recursively counts all Markdown (.md) files under a given directory.
 * Ignores hidden entries (starting with '.') and Docusaurus config files like '_category_.json'.
 *
 * @param {string} dirPath - Absolute path to the target directory.
 * @returns {number} Total number of Markdown files found.
 */
function countMarkdownFiles(dirPath) {
  let count = 0;

  // 讀取當前目錄底下所有項目（檔案與子目錄）
  for (const name of fs.readdirSync(dirPath)) {
    // 忽略隱藏檔與 _category_.json 設定檔
    if (name.startsWith(".") || name === "_category_.json") continue;

    const fullPath = path.join(dirPath, name); // 取得完整路徑
    const stat = fs.statSync(fullPath); // 取得檔案或目錄的狀態資訊

    if (stat.isDirectory()) {
      // 若為資料夾，遞迴統計其內部 Markdown 數量
      count += countMarkdownFiles(fullPath);
    } else if (stat.isFile() && name.endsWith(".md")) {
      // 若為 Markdown 檔案，計入總數
      count += 1;
    }
  }

  return count;
}

/**
 * Converts a relative POSIX path into a URL-safe slug.
 * Ensures cross-platform consistency by normalizing slashes and applying encodeURIComponent.
 *
 * @param {string} relPath - Relative path like 'classic-cnns/vgg'.
 * @returns {string} Encoded URL slug like 'classic-cnns/vgg'.
 */
function toSlug(relPath) {
  return relPath
    .replace(/\\/g, "/") // 替換 Windows 的反斜線為 POSIX 標準分隔符
    .split("/") // 拆成每一層目錄
    .map(encodeURIComponent) // 對每個 segment 做 URL 編碼
    .join("/"); // 再用 / 串起來，形成乾淨穩定的 slug
}

const defaultSlug = `/category/${toSlug(relativeDirPath)}`;

const link = {
  type: "generated-index",
  slug: metadata.link?.slug || defaultSlug, // 優先使用自訂 slug，否則 fallback
  title: metadata.link?.title || baseLabel,
  ...metadata.link, // 保留其他欄位（如 description）
};

/**
 * Sorts subdirectories such that:
 * - Folders with `_category_.json` come first (i.e., manually defined categories)
 * - Others follow, sorted alphabetically
 *
 * @param {string} dir - Absolute path to parent directory
 * @returns {string[]} Sorted list of subdirectory names
 */
function getSortedSubDirs(dir) {
  return fs
    .readdirSync(dir)
    .filter((name) => {
      const fullPath = path.join(dir, name);
      return !name.startsWith(".") && fs.statSync(fullPath).isDirectory();
    })
    .sort((a, b) => {
      const aHasCategory = fs.existsSync(path.join(dir, a, "_category_.json"));
      const bHasCategory = fs.existsSync(path.join(dir, b, "_category_.json"));

      // 有 _category_.json 的排前面
      if (aHasCategory && !bHasCategory) return -1;
      if (bHasCategory && !aHasCategory) return 1;

      // 否則按字母排序
      return a.localeCompare(b);
    });
}