GitHub Link Unfurling Plugin for WordPress

[unscripted]

Overview

Develop a custom WordPress plugin that automatically converts GitHub URLs (e.g., repositories, issues, pull requests) into rich previews when pasted into the Gutenberg block editor or displayed on the frontend. This functionality should mimic link unfurling behavior found in platforms like Slack or Discord but specifically for GitHub.

Functional Requirements

1. Detect GitHub Links

• Monitor for GitHub URLs in post content:
  • Repositories: https://github.com/{owner}/{repo}
  • Issues: https://github.com/{owner}/{repo}/issues/{issue_number}
  • Pull Requests: https://github.com/{owner}/{repo}/pull/{pr_number}

2. Fetch GitHub Metadata

• Use the GitHub REST API to retrieve data:

  • Repositories:
    • Repository name
    • Description
    • Owner (username + avatar)
    • Star count
    • Fork count
    • License (if available)
  • Issues / Pull Requests:
    • Title
    • State (open/closed/merged)
    • Author (username + avatar)
    • Number
    • Labels
    • Created at / Updated at
    • Body (first ~200 characters)

• GitHub API Endpoints:

  • Repo: GET https://api.github.com/repos/{owner}/{repo}
  • Issue/PR: GET https://api.github.com/repos/{owner}/{repo}/issues/{issue_number}

3. Create a Custom Block (or Shortcode Fallback)

• Create a Gutenberg block for rendering GitHub previews:

  • Repos: Show name, description, owner, stars, forks, license.
  • Issues/PRs: Show title, state, author, labels, date.

• Include:

  • GitHub favicon
  • Social preview image (if available)

• Provide a shortcode fallback for non-Gutenberg users.

4. Caching Mechanism

• Cache GitHub API responses using WordPress transients for 24 hours.
• Provide a filter hook to customize the cache expiration.

5. Frontend Rendering

• Ensure previews render on the frontend with:
  • Clean CSS card layout
  • GitHub branding (favicon, avatars, etc.)

6. Graceful Degradation

• If API rate limits are exceeded or the API fails:
  • Render a plain link with a GitHub icon.

Non-Functional Requirements

• Performance:

  • Use lazy loading for API calls (during save or display, not on paste).
  • Leverage caching for API responses.

• Security:

  • Sanitize and escape all fetched data.
  • Respect GitHub API rate limits.
  • Support unauthenticated API access (optionally add a GitHub token in settings for higher rate limits).

• Extendability:

  • Implement hooks and filters for customization (e.g., output format, cache duration).

• Compatibility:

  • Gutenberg block editor.
  • Classic editor via shortcodes.
  • Follow WordPress coding standards.

Suggested Implementation Steps

1. Plugin Scaffolding:

   • Generate standard WordPress plugin structure.
   • Define optional settings (e.g., GitHub API token).

2. Link Detection:

   • Hook into:
     • the_content filter for frontend.
     • Gutenberg editor events (e.g., RichText paste events).

3. GitHub API Integration:

   • Use WordPress HTTP API (wp_remote_get) for GitHub requests.
   • Implement caching with transients.

4. Block Creation:

   • Scaffold a Gutenberg block using @wordpress/create-block.
   • Use PHP render callback for dynamic rendering (ensuring caching).

5. Frontend Output:

   • Apply minimal CSS styling for preview cards.
   • Include GitHub favicon and avatars.

6. Error Handling:

   • Fallback to plain links when API fails or rate limits are hit.

Acceptance Criteria

• GitHub repo, issue, and PR links automatically convert into preview cards.
• Previews display metadata (title, description, owner, stars, etc.).
• Frontend and backend previews are consistent.
• Caching is implemented and configurable.
• Fallback rendering works when API fails.