Jmercer/complete plugin sync fix

[MeelahMe]

Fix plugin documentation sync automation

Summary

This PR fixes critical issues in the plugin documentation sync workflow that prevented it from running end-to-end. The workflow can now successfully authenticate across repositories, locate source files, transform plugin documentation, and build the Hugo site.

Problems Solved

1. Cross-Repository Authentication

Issue: Default GITHUB_TOKEN lacks permissions to access files from other repositories, causing 403 errors when attempting to clone influxdb3_plugins from the docs-v2 workflow.

2. Incorrect Path Resolution in Transformation Script

Issue: The transformation script (port_to_docs.js) reads source paths from docs_mapping.yaml, not from the INFLUXDB3_PLUGINS_PATH environment variable. The configured paths used ../../.ext/influxdb3_plugins but the actual directory structure requires ../../../.ext/influxdb3_plugins.

Testing

Tested with workflow run using plugin basic_transformation:

Results:

• Sparse checkout: Successfully cloned influxdb3_plugins using PAT
• Validation: Passed with 0 errors, 4 warnings (warnings don't block as intended)
• Transformation: Successfully processed plugin README
• Hugo build: Completed successfully
• Screenshot generation: Failed with Playwright module error (non-critical, can be addressed separately)

Related Work

This PR builds on:

• docs-v2 plugin permissions influxdb3_plugins#35 (validation script improvements) - merged to main
• PAT configuration by @jstirnaman (PLUGINS_CONTENT_READ_TOKEN and ISSUES_READ_WRITE_TOKEN)

Impact

Before this PR:

• Workflow failed at transformation step
• Could not authenticate to access cross-repo files
• Could not locate plugin source files

After this PR:

• End-to-end automation working
• Successfully syncs plugin documentation from influxdb3_plugins to docs-v2
• Ready for production use

Future Improvements

1. Screenshot generation: Fix Playwright module loading issue (separate from core automation)
2. Debug step: Can be removed once path fix is confirmed stable in production
3. Directory structure: Consider simplifying by removing the extra docs-v2 nesting (would require changes across workflow)

How to Test

1. Go to Actions → Sync Plugin Documentation
2. Click "Run workflow"
3. Use:
   • Branch: jmercer/complete-plugin-sync-fix
   • Plugin names: basic_transformation
   • Source commit: main
4. Verify transformation succeeds and Hugo builds successfully

Checklist

• Tested with at least one plugin (basic_transformation)
• All critical steps pass (validation, transformation, Hugo build)
• PAT authentication working
• Path resolution corrected
• Screenshot generation (optional, known issue)
• Remove debug step (optional cleanup)

---

cc: @jstirnaman

[jstirnaman]

Question related to the level 1 heading comment in the other PR.

[jstirnaman]

🥇

[jstirnaman]

I don't see in this script where it removes the top-level heading from the README.