JEO

The JEO plugin acts as a geojournalism platform that allows news organizations, bloggers and NGOs to publish news stories as layers of information on digital maps.

With JEO, creating the interaction between data layers and contextual information is intuitive and interactive. You can post geotagged stories and create richly designed pages for each one of the featured stories.

At the same time, by simply imputing the ids of layers hosted on Mapbox, you can manage sophisticated maps without losing performance, add legends directly with HTML and set the map parameters. All directly at the WordPress dashboard.

Compatibility

This repository currently declares Requires PHP: 8.0, with primary validation focused on PHP 8.2 to 8.4 and experimental monitoring on PHP 8.5. The frontend runtime targets Node 24 as the supported project baseline.

Compatibility snapshot validated on May 21, 2026:

• Primary support: PHP 8.2, 8.3, and 8.4.
• Experimental monitoring: PHP 8.5.
• Stable WordPress gate: WordPress 7.0 on PHP 8.2, 8.3, and 8.4.
• Experimental WordPress gate: WordPress 7.0 on PHP 8.5.
• Backward-compatibility smoke tests: WordPress 6.6 on PHP 8.0 and 8.1.

Automation:

• Frontend asset checks run in .github/workflows/node-frontend.yml.
• Static PHP compatibility checks run in .github/workflows/php-compat.yml through PHPCompatibilityWP, configured for PHP 8.0-8.5.
• WordPress runtime smoke tests run in .github/workflows/wordpress-smoke.yml, including an experimental PHP 8.5 job for WordPress 7.0.

Test script coverage:

• phpcs-compat.xml.dist runs PHPCompatibilityWP for generic PHP cross-version compatibility checks against the plugin source.
• scripts/wordpress-smoke.sh can be forced onto PHP 8.5 with WP_CLI_PHP, so the plugin's runtime smoke can be exercised on that line locally and in CI.
• package.json and .npmrc enforce the supported Node runtime through npm's native engine checks before installs continue.
• Size Limit enforces explicit bundle budgets from .size-limit.json instead of relying on generic webpack performance warnings.

Local commands:

nvm use
npm ci
npm run build
npm run build:report
npm run test:unit
npm run audit:npm
composer audit --locked
composer install --no-interaction --no-progress --prefer-dist
vendor/bin/phpcs --standard=phpcs.xml.dist
vendor/bin/phpcs --standard=phpcs-compat.xml.dist

WP_CLI_PHP=/opt/homebrew/opt/php@8.4/bin/php \
WP_DB_HOST=localhost \
WP_DB_NAME=wordpress \
WP_DB_USER=your-user \
WP_DB_PASSWORD='' \
WP_VERSION=7.0 \
bash scripts/wordpress-smoke.sh

scripts/wordpress-smoke.sh honors WP_CLI_PHP, which is useful on Homebrew installs where /opt/homebrew/bin/wp otherwise follows the default php in PATH. For local frontend work, use Node 24. Use PHP 8.5 for local smoke only when you specifically want to inspect the experimental runtime line. Stable wp-cli support for PHP 8.5 is still planned upstream and wp-cli 2.12.0 still emits third-party deprecation noise there.

Setting up local environment

First of all, clone this repository. Note that you can NOT clone it directly in the WordPress plugins directory.

git clone git@github.com:InfoAmazonia/jeo-plugin.git

Set up a WordPress installation. This could be a dedicated installation to develop Jeo or you can use an existing instance you have. (Note: This plugin requires WordPress 6.6+)

Then create a symbolic link inside of wp-content/plugins/jeowp pointing to the src folder in this repository.

ln -s /path/to/jeo-plugin/src /path/to/wordpress/wp-content/plugins/jeowp

Building the plugin

The plugin root for local development and release packaging is src/. Builds compile JavaScript and CSS assets into src/js/build, then compile runtime translation artifacts into src/languages.

Use these commands during local development:

npm run start
npm run build

• npm run start watches the source tree and rebuilds assets while you develop.
• npm run build performs a production build and regenerates compiled translation catalogs in src/languages.

These scripts expect wp (WP-CLI) to be available on your PATH.

Translation workflow

Translation source files are versioned in Git:

• src/languages/jeowp.pot
• src/languages/*.po

Compiled translation files are generated artifacts and are not versioned in Git:

• src/languages/*.mo
• src/languages/*.json

When source strings change, refresh the source catalogs after building assets:

npm run i18n:refresh

This runs npm run build:assets, regenerates src/languages/jeowp.pot, and updates the existing *.po catalogs. Review the updated *.po translations before compiling release artifacts. If you want to run each step manually, use:

npm run build:assets
npm run i18n:pot
npm run i18n:po

After human review of the *.po catalogs, compile the generated runtime files:

npm run i18n:compile

You can also run each compile step directly:

npm run i18n:mo
npm run i18n:json

Before committing translation changes, validate changed PO catalogs with msgfmt --check --statistics. For example:

msgfmt --check --statistics -o /tmp/jeowp-pt_BR.mo src/languages/jeowp-pt_BR.po

Commit reviewed *.po and jeowp.pot changes. Do not commit generated *.mo or *.json files; npm run build and npm run build:release regenerate them for local testing and release packaging.

If you prefer copying files instead of symlinking them into a local WordPress install, use:

rsync --archive --progress --human-readable --delete ./src/ /path/to/wordpress/wp-content/plugins/jeowp/

Releasing

Release packages are built from src/, not from the repository root. When a stable release tag is pushed, the release workflow creates a GitHub Release that keeps GitHub's source-code archives and attaches a built jeowp.zip artifact generated from src/. WordPress.org deployment uses the same src/ tree and publishes assets from .wordpress-org/, but it only runs when the WPORG_DEPLOY_ENABLED repository variable is set to true.

Prerelease branches may carry a SemVer prerelease such as 3.1.0-rc.1 while WordPress.org stays on the latest stable release. Before creating a stable release tag, run npm run sync:version and keep these files aligned:

• src/jeo.php
• src/readme.txt
• package.json
• package-lock.json
• .wordpress-org/

The release workflow now validates that:

• the plugin version in src/jeo.php matches JEO_VERSION
• package.json and the root package entry in package-lock.json match the plugin version
• the Stable tag in src/readme.txt matches the plugin version for the tagged stable release
• the release tag is a stable x.y.z version
• the built release tree from src/ passes WordPress Plugin Check when staged as jeowp/

Pull requests and pushes also run the same staged Plugin Check build through .github/workflows/plugin-check.yml, so WordPress.org compliance failures are caught before the release tag workflow.

Pre-release tags such as -rc are intentionally blocked from the stable release pipeline. Stable tag releases only publish a GitHub Release after Plugin Check passes; a failing check blocks all publish steps. WordPress.org deployment runs after the GitHub Release step only when WPORG_DEPLOY_ENABLED=true, so the same tag workflow can be rerun later after WordPress.org SVN access is available.

Release validation and packaging should use:

npm ci
npm run build

The attached jeowp.zip mirrors the WordPress.org deploy package: it contains the built contents of src/ under the jeowp/ plugin slug directory, including generated *.mo and *.json translation catalogs, ready for manual installation in WordPress.

Documentation

The documentation source lives in docs/. The published static site lives in site/ and is generated with MkDocs.

To rebuild it locally:

python3 -m pip install -r requirements-docs.txt
python3 -m mkdocs build --clean

Changes to docs/, mkdocs.yml or requirements-docs.txt on master automatically regenerate and commit site/ through .github/workflows/docs-site.yml.