# 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**.

## How to Zip the Plugin for GitHub Releases

When attaching the plugin to a GitHub release:

1. Zip **only the contents of the plugin folder**, not the parent folder.
2. Ensure `projects-portfolio.php` and `/includes`, `/admin`, `/templates`, `/assets` are at the root level of the ZIP.
3. Name the ZIP clearly (e.g. `projects-portfolio-1.0.0.zip`).
4. Go to your GitHub repo → **Releases** → **New Release**.
5. Tag the release with the version number (e.g., `1.0.0`).
6. Upload your correctly structured ZIP as a release asset.

Your users will be redirected to this file when they use the `/download/` endpoint.

## 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).