WordPress Hslg Docs Publisher

WordPress Hslg Docs Publisher module

Imports versioned documentation automatically when activated or upgraded; keeps stable WordPress page IDs, ownership metadata, unlimited post revisions and collision protection.

Why this plugin exists

The documentation publisher keeps WordPress-hosted reference material synchronized with a reviewed release bundle. It is separate from the visual presenter and API plugin, so adding documentation never needs a database schema migration or a mobile app build. hslg-docs-publisher.php loads the publisher and automatic lifecycle hooks. The canonical Markdown is in the project source; WordPress is a published, revisioned rendering of that source.

The bundle format

bundle/pages.json is generated by tools/docs/build_docs.py. Each page has a stable key such as app/architecture/environments, a title, a Markdown body, rendered HTML and hashes. docs/publication/manifest.json mirrors page and source coverage. The publisher validates the key namespace, uniqueness, parent existence and hashes before writing. The separate source-to-published check must fail if the HTML is not the actual verified rendering of its Markdown.

How auto-publication starts

src/AutoSync.php registers WordPress plugin activation, upgrade notifications, admin activity and a scheduled retry. When the installed bundle's checksum differs from the previously applied checksum, the publisher attempts to apply the release. A lock reduces concurrent publication. The implementation stores success/failure status in WordPress options and shows an administrator notice when blocked. Routine publication does not require root SSH or a manual WP-CLI command.

Exact update semantics

src/Publisher.php first checks whether a page with that document key already exists. A page that is HSLG-owned may be updated under its original WordPress post ID through wp_update_post(), preserving normal WordPress revisions when revisions are enabled. A new page is created with wp_insert_post(). If an unrelated page occupies the planned path, the publisher stops rather than claiming it. If an editor changed an owned page since the previous bundle, the update blocks rather than losing the edit. A missing document in a later bundle does not authorize deleting its previous WordPress page.

What a revision means

WordPress revisions track published page-body changes. They do not replace the append-only HSLG development chronology, which records source work and decisions. The publisher's release gate must compare both: the source documentation update has a history record, and the server update must reuse the page ID and generate a revision for changed text. An unchanged page should not create noise by receiving a new revision every release. A configured finite WordPress revision limit could prune history and is therefore incompatible with the stated requirement.

Operator errors and recovery

If page paths collide, verify ownership and rename the *planned new namespace* rather than deleting an unrelated post. If a manual edit blocks publication, compare the edit to the source Markdown, incorporate the approved text into the next project release, and retry. If a plugin update is interrupted, the next scheduled/admin run should resume idempotently. A clean WordPress restore can republish from a source bundle, but WordPress-only edits and their original revisions are not recoverable after total data loss without surviving backups.

Testing this plugin

Use the PHP publisher mock tests to verify first import, no-op repeat, revision update, path collision, manual edit conflict, interrupted upgrade and absence of destructive write calls. Review local quality gates for page depth and source coverage before generating the ZIP. After WordPress installation, verify actual page IDs, revision links, navigation, frontend HTML, admin notices and the number of published pages. Local tests do not prove live publication on media.hslg.uk.

Source files in this module

Maintenance and evidence

Check all affected file references and the matching human-readable user/architecture page when source changes. Run the module’s contract or governance checks; staging, payment and native hardware tests remain independent of source inventory coverage.