Headless Portfolio CMS

OVERVIEW

Most developers and digital marketers who want a portfolio website face the same frustrating choice: use a rigid theme that doesn’t reflect their actual work, or build a fully custom frontend and somehow connect it to a manageable content backend. WordPress is everywhere, but its native structure wasn’t built for headless, API-first use cases.

I built the Headless Portfolio CMS plugin to solve this problem — for myself first, and then for other developers and agencies who want to manage their portfolio content inside WordPress but serve it through a modern frontend like Next.js or React. The plugin turns any WordPress installation into a clean, structured content backend with REST API endpoints ready to connect to any frontend framework.

Beyond solving the problem, I wanted to go through the full process of shipping a real, production-grade WordPress plugin — including navigating the official WordPress.org Plugin Repository review process, which is notoriously thorough.

THE CHALLENGE

The technical challenge was fairly clear: design a plugin architecture that’s flexible enough to handle diverse portfolio needs (projects, skills, experience, testimonials, education) while staying clean, performant, and REST API-ready out of the box.

The harder challenge — one I didn’t fully anticipate — was the WordPress.org review process. The Plugin Repository team reviews every submission for coding standards, security practices, and architectural decisions before approving anything. It’s rigorous, and they don’t approve plugins that cut corners.

Specific challenges:

• Designing a Custom Post Type (CPT) architecture that’s genuinely useful across different portfolio types without becoming bloated.
• Building REST API endpoints that expose structured, well-formed data — not just dumping raw WordPress post objects.
• Passing the WordPress.org review — which flagged issues across multiple rounds including ownership verification, inline style violations, and permission_callback compliance.
• Making the plugin work seamlessly with modern headless frameworks (Next.js, React) without requiring any configuration on the frontend developer’s side.
• Keeping the plugin lightweight — no unnecessary dependencies, no bloat, no admin UI complexity that confuses non-technical users.

MY APPROACH / STRATEGY

Architecture first

Before writing a single line of PHP, I mapped out the content model. A portfolio has predictable content types: projects, skills, testimonials, work experience, education, and a resume/profile. I designed a CPT for each, with custom fields that make sense for that content type — not just generic key-value pairs.

REST API-first design

Every CPT needed to expose its data through clean, documented REST API endpoints. I designed the API response structure first — what shape should the data be in when a Next.js page fetches it? — and then built the PHP to produce that shape. This meant the plugin was immediately usable with any modern frontend without any custom adapter code.

Security and permissions from day one

One of the most common reasons WordPress plugins fail review is improper permission handling on REST API endpoints — either leaving endpoints open to anyone or using deprecated callback patterns. I implemented proper permission_callback functions for every endpoint from the start, using WordPress’s built-in capability system.

Compliance-first submission strategy

Rather than rushing the submission, I audited my own code against the WordPress Plugin Handbook and common review failure points before submitting. This didn’t prevent all issues — the review team still caught things — but it reduced the number of revision rounds significantly.

EXECUTION & TOOLS USED

Tech Stack

PHP 7.4+ · WordPress REST API · Custom Post Types · register_post_type() · register_rest_route() · SVN / TortoiseSVN · VS Code · WordPress Plugin Handbook

Custom Post Types Built:

• Projects — with fields for title, description, tech stack, live URL, GitHub URL, featured image, and project type.
• Skills — categorized by skill type (technical, soft, tool) with proficiency level.
• Testimonials — with client name, role, company, testimonial text, and date.
• Work Experience — with company, role, start/end date, responsibilities, and achievements.
• Education — with institution, degree, field, dates, and notes.
• Profile/Resume — a singleton CPT for bio, headline, and summary data.

The Review Process — What Actually Happened:

The WordPress.org review process took multiple rounds. Here’s what was flagged and how I resolved it:

1. Round 1 — Ownership verification: The review team couldn’t verify that the plugin’s listed contributor matched the submitting account. Resolved by updating the plugin header and contributor list to match the WordPress.org username exactly (aladilashrafi).
2. Round 2 — Inline styles: Several places in the admin UI used inline style attributes instead of properly enqueued stylesheets. Moved all styling to a registered admin CSS file.
3. Round 3 — permission_callback: Some REST API routes were using a deprecated callback naming pattern. Rewrote all permission callbacks to follow the current WordPress REST API standard — using __return_true() for public endpoints and proper capability checks for authenticated ones.
4. After the third revision, the plugin was reviewed and approved. It’s now live on the WordPress.org Plugin Repository.

RESULTS & METRICS

This project wasn’t about revenue or ROAS — it was about shipping something real, to a real standard, in a real ecosystem. The outcomes that matter here are:

• Successfully approved and live on the official WordPress.org Plugin Repository — one of the more rigorous software review processes for open-source PHP projects.
• Plugin works out of the box with Next.js, React, and any headless frontend — no custom adapter or configuration needed.
• All 6 content types (Projects, Skills, Testimonials, Experience, Education, Profile) expose clean, structured REST API endpoints.
• Used as the backend for my own portfolio at adilashrafi.com — built on Next.js 14 App Router.
• Code is public, documented, and maintained to WordPress Coding Standards — meaning any developer can install, extend, or fork it.

KEY LEARNINGS / TAKEAWAYS

• Design the data shape before writing code. Starting with what the API response should look like — not how the PHP should work — resulted in a much cleaner architecture. The frontend perspective forced better backend decisions.
• The WordPress review process is genuinely useful. Every issue the reviewers flagged was a legitimate problem — not bureaucratic box-ticking. The review process made the final plugin meaningfully better than my first submission.
• Permissions are not optional. Improper permission_callback implementations are one of the most common WordPress plugin security issues. Getting this right from the start is non-negotiable for any production plugin.
• Build for extension, not just for your own use case. The CPT structure I chose is generic enough that developers with very different portfolios can use the same plugin without modification. Thinking about the second user, not just yourself, produces better software.
• Shipping to a real repository changes how you write code. Knowing the plugin would be reviewed by the WordPress team — and potentially used by thousands of people — raised my standards in ways that building for personal use alone never does.