208 lines
6.6 KiB
Markdown
208 lines
6.6 KiB
Markdown
# 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<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](#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).
|