Projects-Portfolio/README.md

Projects Portfolio

Create a beautifully structured, developer-first showcase directory for your WordPress plugins, themes, and patterns - powered by git.

What It Does

Projects Portfolio adds a custom post type (projects) and taxonomy (project-type) to your WordPress admin, allowing you to:

• Add plugins, themes, or patterns as projects.
• Connect each project to a git repository.
• Automatically fetch and display data like:
  • Latest version
  • Stars, forks, issues
  • License and language
  • Download counts
• Create a public download URL: /download/ID/
• Track and sort download metrics
• Render archive and single views with theme fallbacks or built-in templates
• Customize display settings via a clean settings page
• Provide social sharing buttons using Tabler Icons
• Use built-in REST API endpoints for listing and querying project data

---

Installation

From GitHub

1. Download the latest ZIP from the GitHub Releases page.
2. Go to your WordPress Dashboard → Plugins → Add New → Upload Plugin.
3. Upload the ZIP and activate the plugin.

From keithsolomon.net

1. Visit the official plugin page: Projects Portfolio.
2. Download the ZIP.
3. Install it via the WordPress dashboard like above.

---

Usage

Add a New Project

1. In the WordPress admin, go to Projects → Add New.
2. Add your project title, description, and featured image.
3. Select a Project Type: Plugin, Theme, or Pattern.
4. In the sidebar, choose Provider (GitHub or Gitea) and paste the Repository URL (e.g., https://github.com/username/repo or https://codeberg.org/username/repo).
5. For Gitea projects, optionally set a Gitea Base URL to override the global default.
6. Publish.

Enable Download Link

Each project automatically gets a unique download endpoint:

Example: https://example.com/download/123

This URL fetches the latest .zip release from the project's host (GitHub or Gitea) and increments the download count.

Settings Overview

Navigate to Projects → Settings to configure:

General Settings

• GitHub API Token – Recommended for authenticated requests (avoids GitHub rate limits).
• Default Gitea Base URL – Used when a Gitea project doesn't specify one. Defaults to https://codeberg.org.
• Gitea API Token – Recommended for authenticated Gitea requests.
• Telemetry – Toggle to help improve the plugin.

Templates Settings

Enable/disable the following GitHub data in your project views:

• Version
• Last Updated
• License
• Language
• Downloads
• Stars / Forks / Issues
• Repo Owner

Archive Settings

Toggle components for the project archive view:

• Archive Title
• Project Title
• Project Excerpt
• Project Buttons

Connect Your GitHub Repo

To connect a project to GitHub:

1. Paste the full repo URL into the Repository URL field when editing a Project.
2. Make sure your repo has a release with a .zip asset or a valid zipball_url.

Optional: Add a GitHub API Token

To avoid hitting rate limits or improve reliability:

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens.
2. Generate a token (no scopes required).
3. Paste it into the settings screen under GitHub API Token.

Connect Your Gitea Repo

To connect a project to a Gitea instance (self-hosted or public):

1. Set Provider to Gitea in the project editor.
2. Paste the full repository URL into Repository URL (e.g., https://codeberg.org/username/repo).
3. Optionally override the Gitea base URL for this project (leave blank to use the global default).
4. Make sure the repo has a release with a .zip asset, or any tag — the plugin will fall back to the source archive URL.

Optional: Add a Gitea API Token

To avoid rate limits or improve reliability:

1. In your Gitea instance, go to Settings → Applications and generate a token.
2. Paste it into the plugin settings screen under Gitea API Token.

Building a Release

Releases are automated via GitHub Actions. To cut a new release:

1. Bump PROJECTS_PORTFOLIO_VERSION and the plugin header Version: in projects-portfolio.php.
2. Commit and push to main.
3. Tag the release commit: git tag -a v1.1.1 -m "v1.1.1 — short summary".
4. Push the tag: git push origin v1.1.1.

The .github/workflows/release.yml workflow runs and:

• Builds projects-portfolio-v<version>.zip containing only the runtime files (projects-portfolio.php, admin/, assets/, includes/, languages/, templates/, README.md, LICENSE).
• Uploads the zip as a workflow artifact.
• Creates (or updates) the matching GitHub Release with the zip attached.

Dev-only paths (composer.json, composer.lock, vendor/, tests/, plans/, specs/, .github/, .gitignore, .vscode/, .claude/) are intentionally excluded.

How to Zip the Plugin for GitHub Releases

This is now automated. See Building a Release above — pushing a v* tag triggers .github/workflows/release.yml which builds and publishes the zip.

REST API Endpoints

All Projects

GET /wp-json/projects/v1/projects

Supports optional query params:

• page
• per_page

Popular Projects

GET /wp-json/projects/v1/popular

Returns the most downloaded projects.

Template Integration

You can override the plugin templates in your theme:

• single-projects.php
• archive-projects.php
• taxonomy-project-type.php

Just copy the templates from the plugin's /templates/ folder into your theme's root and customize.

Social Sharing Buttons

Each project includes social sharing links for:

• Facebook
• Twitter/X
• LinkedIn
• Reddit
• Pinterest
• WhatsApp
• Email

Developer Notes

• All public-facing code is translation-ready.
• Full support for Full Site Editing (FSE) and Classic themes.
• REST API ready and easily extendable.
• Clean separation of concerns: CPT/taxonomy, settings, metaboxes, API, styling.

Support & Contributions

Have a feature request or bug report? Open an issue on the repo or contribute via pull request.

License

Projects for WordPress is licensed under the GNU GPL v2+.

Author

Built and maintained by Keith Solomon.

Follow on Twitter.