BlueTheme Docs

Developer guide

For developers who extend BlueTheme from a child theme or a plugin, and for those working on the theme itself. Using the theme is covered by the user guide.

Extending the theme

Rules that keep extensions working with the theme:

  • Both directions. Persian sites are right to left. Use logical CSS properties (margin-inline-start, inset-inline-end, text-align: start) and never assume the start side is the left.
  • Translatable. Wrap every string in __() and its relatives with your own text domain.
  • Escaped. Escape all output (esc_html, esc_attr, esc_url, wp_kses_post), check capabilities and nonces on every request, and clean every input.
  • Local. The theme loads nothing from other servers by default (Google services may be blocked for visitors). Bundle your assets.
  • Hooks first. Use a filter or action when there is one; copy a template file only when there isn't.

Working on the theme

pnpm install
composer install      # from PowerShell on Windows
pnpm build            # copies Bootstrap, fonts and icons into the theme, builds JS and CSS
pnpm env:plugins      # WooCommerce, Persian WooCommerce and ZarinPal for the dev sites
pnpm env:start        # Persian site on :8888, English site on :8889 (admin / password)
pnpm start            # rebuilds on change
Path What it is
bluetheme/ The theme: what ships in the zip.
bluetheme/inc/ PHP classes under the BlueTheme\ namespace, one folder per feature, loaded by Autoloader.php. Theme.php lists the services.
bluetheme/elements/ Builder elements, one folder each.
bluetheme/demos/ Bundled demo packages.
bluetheme-child/ The ready-made child theme.
src/ JavaScript (React for the builder, Theme Options and wizard) and SCSS, built into bluetheme/build/.
tools/ Build, packaging, translation, demo, documentation and test scripts.
tests/ PHPUnit (tests/php) and Playwright (tests/e2e) tests.
docs/ This documentation: user/ (Persian and English), dev/, and reference/ data.

Checks

Command Checks
pnpm lint:js, pnpm lint:css JavaScript and CSS style; CSS that uses left and right instead of logical sides.
composer lint WordPress Coding Standards and PHP 8.0 compatibility.
composer analyse PHPStan, level 5.
composer test PHPUnit.
pnpm env:smoke Both dev sites: PHP errors, direction, assets from other servers.
pnpm test:e2e Playwright: keyboard use, the live builder.
pnpm qa:crawl, qa:a11y, qa:perf, qa:security, qa:rtl Every page with WP_DEBUG, accessibility, Lighthouse, routes and permissions, layout in both directions. See quality checks.

Translations

pnpm i18n updates languages/bluetheme.pot (including the element labels from config.json, through tools/element-strings.mjs), merges it into fa_IR.po and compiles the .mo and JSON files for scripts. Every string needs a Persian translation before a release.

Documentation

pnpm docs:export  # with wp-env running: Theme Options and elements from both dev sites
pnpm docs:build   # builds the site into bluetheme/docs/
pnpm docs:screenshots   # with wp-env running: retakes the guide's pictures in both languages

The user guide is in docs/user/fa/ and docs/user/en/, with screenshots in docs/user/img/. The navigation is docs/nav.json. The reference pages and the hooks reference are generated, so run pnpm docs:export after changing options or elements. pnpm docs:screenshots imports the Corporate and Clothing shop demos on each dev site in turn, takes each picture with the control the text talks about outlined, and removes the demo; -- --site=fa --only=builder,shop retakes some. A page not translated yet is left out of that language's navigation (the build warns), and links to it open the English page.

Releases

pnpm zip builds the documentation and writes dist/bluetheme-{version}.zip and dist/bluetheme-child-{version}.zip. Pushing a v* tag that matches the version in bluetheme/style.css runs the release workflow, which builds the zips and attaches them to a GitHub release. Changes are listed in CHANGELOG.md.