Enhance fetch-docs script with plugin and version filtering options

Author: cklei-carly

README.md

@@ -56,6 +56,41 @@ npm run fetch-docs
 npm run fetch-docs:cache
 ```
 
+##### Filtering by Plugin and/or Version
+
+Pass `--plugin` and `--version` flags (directly via `tsx`) or use the `FETCH_PLUGIN` / `FETCH_VERSION` environment variables (recommended on Windows, where `npm run -- ` does not forward args correctly).
+
+**PowerShell (Windows) — use env vars:**
+```powershell
+# Single plugin (all versions)
+$env:FETCH_PLUGIN='simple-contact-form'; npm run fetch-docs
+
+# Single plugin, single version
+$env:FETCH_PLUGIN='simple-contact-form'; $env:FETCH_VERSION='2.x'; npm run fetch-docs
+
+# Multiple plugins (comma-separated)
+$env:FETCH_PLUGIN='filament-tree,filament-firewall'; npm run fetch-docs
+
+# Combined with cache-only
+$env:FETCH_PLUGIN='simple-contact-form'; npm run fetch-docs:cache
+```
+
+**bash / macOS / Linux — env vars also work:**
+```bash
+FETCH_PLUGIN=simple-contact-form npm run fetch-docs
+FETCH_PLUGIN=simple-contact-form FETCH_VERSION=2.x npm run fetch-docs
+FETCH_PLUGIN=filament-tree,filament-firewall npm run fetch-docs
+```
+
+**Or call `tsx` directly (works everywhere):**
+```bash
+npx tsx scripts/fetch-docs.ts --plugin=simple-contact-form
+npx tsx scripts/fetch-docs.ts --plugin=simple-contact-form --version=2.x
+npx tsx scripts/fetch-docs.ts --plugin=filament-tree --plugin=filament-firewall
+```
+
+> **Note:** `npm run fetch-docs -- --plugin=...` does **not** work on Windows because npm strips args after `--` on that platform. Use the env var or direct `tsx` approach instead.
+
 #### Build & Deploy
 
 Since GitHub Actions may hit API limits easily, we recommend building locally and pushing the static site.
@@ -349,8 +384,12 @@ npm run build:cache      # Build using cached documentation (faster)
 npm run build:static     # Build for static export (used by GitHub Actions)
 
 # Documentation Management
-npm run fetch-docs       # Fetch documentation from GitHub
-npm run fetch-docs:cache # Use cached docs, skip GitHub fetch
+npm run fetch-docs                                                      # Fetch all documentation from GitHub
+npm run fetch-docs:cache                                                # Use cached docs, skip GitHub fetch
+$env:FETCH_PLUGIN='<id>'; npm run fetch-docs                           # PowerShell: single plugin
+$env:FETCH_PLUGIN='<id>'; $env:FETCH_VERSION='<ver>'; npm run fetch-docs  # PowerShell: plugin + version
+FETCH_PLUGIN=<id> npm run fetch-docs                                    # bash: single plugin
+npx tsx scripts/fetch-docs.ts --plugin=<id> --version=<ver>            # Direct tsx (all platforms)
 
 # Type Checking
 npm run types:check      # Run TypeScript type checking

scripts/fetch-docs.ts

@@ -11,15 +11,50 @@ const octokit = new Octokit({
 });
 
 // Parse command line arguments
-// Usage: tsx scripts/fetch-docs.ts [--cache-only|--offline]
-// --cache-only: Skip fetching from GitHub and use only cached content
+// Usage: tsx scripts/fetch-docs.ts [--cache-only|--offline] [--plugin=<id>] [--version=<ver>]
+// --cache-only / --offline : Skip fetching from GitHub and use only cached content
+// --plugin=<id>            : Only fetch docs for the plugin with this id (can repeat)
+// --version=<ver>          : Only fetch docs for this version string (can repeat)
+//
+// Examples:
+//   tsx scripts/fetch-docs.ts --plugin=filament-tree
+//   tsx scripts/fetch-docs.ts --plugin=filament-tree --version=4.x
+//   tsx scripts/fetch-docs.ts --plugin=filament-tree --plugin=filament-firewall
 const args = process.argv.slice(2);
 const cacheOnly = args.includes('--cache-only') || args.includes('--offline');
 
-if (cacheOnly) {
-  console.log('🔌 Running in cache-only mode. Will not fetch from GitHub.');
+// Collect repeated --plugin and --version values (supports both --plugin=id and --plugin id)
+function parseRepeatedArg(argName: string, argv: string[]): string[] {
+  const values: string[] = [];
+  const prefix = `--${argName}=`;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith(prefix)) {
+      values.push(argv[i].slice(prefix.length));
+    } else if (argv[i] === `--${argName}` && i + 1 < argv.length) {
+      values.push(argv[++i]);
+    }
+  }
+  return values;
+}
+
+// CLI args take priority; fall back to env vars (FETCH_PLUGIN / FETCH_VERSION).
+// Env vars support comma-separated values: FETCH_PLUGIN=filament-tree,filament-firewall
+function splitEnvList(val: string | undefined): string[] {
+  return val ? val.split(',').map(s => s.trim()).filter(Boolean) : [];
 }
 
+const filterPlugins  = parseRepeatedArg('plugin',  args).length
+  ? parseRepeatedArg('plugin',  args)
+  : splitEnvList(process.env.FETCH_PLUGIN);
+
+const filterVersions = parseRepeatedArg('version', args).length
+  ? parseRepeatedArg('version', args)
+  : splitEnvList(process.env.FETCH_VERSION);
+
+if (cacheOnly)             console.log('🔌 Running in cache-only mode. Will not fetch from GitHub.');
+if (filterPlugins.length)  console.log(`🔍 Filtering plugins:  ${filterPlugins.join(', ')}`);
+if (filterVersions.length) console.log(`🔍 Filtering versions: ${filterVersions.join(', ')}`);
+
 function getCachePath(owner: string, repo: string, ref: string, path: string): string {
   // Use a Safe path structure: .cache/raw/owner/repo/ref/path
   // Replce any potential invalid characters in ref just in case, though usually refs are file-safe or close to it.
@@ -374,7 +409,17 @@ async function fetchPluginDocs() {
   const rootMetaPages: string[] = [];
   const rootMetaTitles: Record<string, string> = {};
 
-  for (const plugin of config.plugins) {
+  const plugins = filterPlugins.length
+    ? config.plugins.filter(p => filterPlugins.includes(p.id))
+    : config.plugins;
+
+  if (filterPlugins.length && plugins.length === 0) {
+    console.error(`❌ No plugins matched: ${filterPlugins.join(', ')}`);
+    console.error(`   Available ids: ${config.plugins.map(p => p.id).join(', ')}`);
+    process.exit(1);
+  }
+
+  for (const plugin of plugins) {
     const [owner, repoName] = plugin.repo.split('/');
 
     const pluginDir = join('content', 'docs', plugin.id);
@@ -397,7 +442,16 @@ async function fetchPluginDocs() {
     };
     writeFileSync(join(pluginDir, 'meta.json'), JSON.stringify(rootMeta, null, 2));
 
-    for (const version of plugin.versions) {
+    const versions = filterVersions.length
+      ? plugin.versions.filter(v => filterVersions.includes(v.version))
+      : plugin.versions;
+
+    if (filterVersions.length && versions.length === 0) {
+      console.warn(`⚠️  No versions matched for ${plugin.id}: ${filterVersions.join(', ')} — skipping plugin.`);
+      continue;
+    }
+
+    for (const version of versions) {
       const versionDir = join('content', 'docs', plugin.id, version.version);
       mkdirSync(versionDir, { recursive: true });