Puock: a WordPress theme built around a Vue 3 settings panel and no-refresh navigation

The gap Puock fills between a plain blog theme and a plugin stack

A default WordPress theme gives you templates and menus. Everything else, front-end registration, third-party login, a user centre, captcha on comments, ad slots, a table of contents, is normally a separate plugin, and each plugin brings its own settings page and its own update risk. Puock bundles those into one theme. The README lists QQ, Github, Gitee and Weibo login, a front-end user centre, comment ajax loading, ad positions, shortcodes for download and members-only content, and a reading time counter as built-in features rather than add-ons.

The audience is narrower than "WordPress users". It is people running a content site who want a front-end account system and a dark mode toggle without paying for a commercial theme or wiring six plugins together. The theme also ships three layout presets (blog, CMS and company), which tells you the author expects it to be used for more than a personal diary. If your site is a WooCommerce store or a membership business with paid subscriptions, this is not the layer you want handling accounts.

How the PHP templates, the Vue 3 admin panel and the build pipeline fit together

The repository layout is a conventional WordPress theme with an unusual split. The front end is PHP: index.php, single.php, page.php, category.php, search.php and 404.php sit at the top level, with inc/, templates/, pages/ and gutenberg/ holding the rest. The admin configuration screen is not PHP-rendered. The feature list describes it as "Vue3+NaiveUI集成的高颜值后台配置", a Vue 3 and NaiveUI settings interface, and package.json confirms a Node toolchain with gulp, gulp-babel, gulp-less, gulp-clean-css and gulp-uglify, exposed through two scripts, build and dev.

That means two toolchains coexist in one repository. PHP serves the site; Node builds the assets and the settings UI. The no-refresh loading and the ajax comment loading are front-end behaviours, and the README's topic list names pjax, which is the usual mechanism for swapping page content without a full reload. The documentation does not describe the request flow in detail, so treat the exact pjax boundaries as something to observe on a running install rather than something the README specifies. The practical consequence of the split is that anyone editing theme JavaScript or LESS needs Node and pnpm or npm installed, while anyone editing templates needs only PHP.

Installing Puock from the release zip, not the repository

The installation instructions are explicit about one thing that trips people up. Download only the release package named Puock-VX.Y.Z.zip from the releases page. The README warns that cloning the repository, or downloading the auto-generated Source code (zip) or Source code (tar.gz) archives, gives you a source snapshot that is not a valid install package. The latest release listed is v2.11.0, published on 2026-08-20.

Once you have the zip, upload it through the WordPress admin:

# Nothing to run here; the install is done in the browser.
# WordPress admin: Appearance > Themes > Add New > Upload Theme
# Select the file named like Puock-V2.11.0.zip and activate it.

The README also asks you to back up your data before installing, because theme fields can overwrite existing values. Environment requirements are WordPress 6.0 or newer and PHP 7.4 or newer. After activation, the theme settings screen is where the layout preset, colour mode behaviour and integrations are configured. Documentation lives at docs.puock.com, with a usage guide in USAGE.md for features such as friendly links and message boxes.

If you want to change the theme's own CSS or JavaScript rather than its options, the build scripts are the entry point:

npm install
npm run build

The package.json defines build as gulp build and dev as gulp watch, so npm run dev is the watch mode while you edit LESS or JavaScript sources. Nothing in the README states that this step is required for a normal install; it is only for source-level changes.

Where Puock is the wrong tool

The clearest limitation is structural. Puock is a classic PHP theme, not a block theme. The repository has a gutenberg/ directory, but the feature list and the template files describe a theme whose layouts are chosen from presets, not assembled in the site editor. If your workflow depends on editing templates visually with the block editor, or on distributing your own block patterns, this theme fights you.

The second limitation is support language. The README, the usage guide and the issue tracker are written in Chinese, with an English README file present but the documentation links pointing to Chinese-language pages. An English-speaking operator can install and use the theme, but the detailed feature instructions are in Chinese, and the community channel advertised is a QQ or WeChat group. That is a real constraint on how quickly you can resolve a problem.

The third is upgrade risk. Puock stores a lot of behaviour in theme options, and the README itself warns about data fields being overwritten during installation. A theme that owns user accounts, login providers and comment behaviour has more surface to break on update than a theme that only owns markup. The releases show a steady cadence, v2.10.2 on 2026-05-31, v2.10.3 on 2026-08-15 and v2.11.0 on 2026-08-20, so updates arrive often enough that you need a repeatable way to test them. The README does not document a rollback procedure.

Puock against a block theme plus a plugin stack

The obvious alternative is a default block theme such as Twenty Twenty-Four or Twenty Twenty-Five, paired with plugins for the features you actually need: a social login plugin, a captcha plugin, an SEO plugin, a table of contents plugin. The difference in approach is ownership. With the block theme route, each feature has its own maintainer and its own release cycle, and you can drop one without touching the others. With Puock, one project owns all of it, which means one upgrade path and one place to look when something breaks, but also one point of failure.

A second alternative is a commercial multipurpose theme. Those usually offer a visual builder and paid support, at the cost of a licence fee and often heavier front-end assets. Puock's positioning is the opposite: GPL-3.0, no licence fee, and a settings panel built with Vue 3 and NaiveUI rather than a page builder. If your reason for looking at Puock is the dark mode toggle and the no-refresh navigation, a block theme with a small amount of custom CSS gets you part of the way; it will not get you the front-end user centre or the aggregated login providers.

Licence, attribution and what an upgrade actually costs

Puock is licensed under GPL V3.0, and the README adds a condition in plain language: keep the attribution in the theme footer. For a GPL theme that footer credit is the author's stated expectation, and removing it is the kind of change that puts you outside the project's terms. This is not legal advice; if you plan to redistribute a modified version, read the licence text in LICENSE yourself.

The upgrade cost is mostly operational. Because the theme is not archived and the last push was on 2026-09-11, releases and commits are still arriving, so you should assume you will be applying updates rather than freezing a version forever. The README's own warning about backing up before installation applies with more force to upgrades than to a fresh install, since an upgrade runs against data the theme already wrote. A workable pattern is to keep a staging copy, install the new release zip there first, and check the front-end login, comment and settings screens before touching production. The repository does not document a downgrade path, so the backup is the rollback.

Editorial conclusion

Puock fits operators of a self-hosted blog, CMS or company site on WordPress 6.0+ and PHP 7.4+ who want login, comment and SEO features without assembling a plugin stack, and who are willing to test upgrades on a staging copy first. It is the wrong choice if you need a full site editor block theme, if you cannot keep the footer attribution the licence asks for, or if you expect the maintainer to answer support requests in English. Before adopting it, install the matching release zip on a staging site, enable the front-end user centre and one third-party login, then confirm on the published documentation which settings the theme stores in the database so your backup covers them.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Licoy/wordpress-theme-puock on GitHub
3. Project website
4. README
5. Releases