# Projects Portfolio Create a beautifully structured, developer-first showcase directory for your WordPress® plugins, themes, and patterns - powered by [GitHub](https://git.keithsolomon.net/Solo-Web-Works/Projects-Portfolio). ## 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 GitHub 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](https://git.keithsolomon.net/Solo-Web-Works/Projects-Portfolio/releases). 2. Go to your WordPress® Dashboard → Plugins → Add New → Upload Plugin. 3. Upload the ZIP and activate the plugin. ### From [keithsolomon.net](https://keithsolomon.net) 1. Visit the official plugin page: [Projects Portfolio](https://keithsolomon.net/projects/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 - GitHub 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 **GitHub URL** field when editing a Project. 2. Make sure your GitHub 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.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](#building-a-release) above — pushing a `v*` tag triggers `.github/workflows/release.yml` which builds and publishes the zip. ## REST API Endpoints ### All Projects ```http GET /wp-json/projects/v1/projects ``` Supports optional query params: - `page` - `per_page` ### Popular Projects ```http 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 [GitHub](https://github.com/robertdevore/projects-portfolio/issues) or contribute via pull request. ## License Projects for WordPress® is licensed under the [GNU GPL v2+](http://www.gnu.org/licenses/gpl-2.0.txt). ## Author Built and maintained by [Robert DeVore](https://www.robertdevore.com). Follow on [Twitter](https://twitter.com/deviorobert) or sponsor development on [GitHub Sponsors](https://github.com/sponsors/robertdevore).