Draconai Documentation

dd_id_h9qvuokrif
Special

DevDocs -> WordPress Publishing Pipeline (Hash Artifacts)

Table of Contents

This page describes the current intended pipeline for publishing DevDocs pages into WordPress.

Goals

  • Author pages directly in ./docs/devdocs/ (source of truth).
  • Detect changes cheaply and deterministically.
  • Ensure WordPress ends up exactly matching the DevDocs set (add/update/delete) with minimal work.

Key Concepts

  • Stable page identity: every DevDocs page must contain a stable identifier (DEVELOPERDOCS_ID). This identifier is the primary key for reconciliation in WordPress.
  • Hash artifacts: hashes are used to detect changes, not to define identity.
  • One artifact per page: the build produces one generated artifact file per page, named by its hash, plus an index/manifest.

Page Header Contract

  • DEVELOPERDOCS_ID: dd_id_<10 lowercase alphanumeric>
  • Mandatory for every DevDocs page.
  • Auto-generated on first page creation, then stable forever.
  • The alphanumeric string is always lowercase.
  • PARENT_DEVELOPERDOCS_ID: dd_id_<10 lowercase alphanumeric>
  • Optional.
  • If present, it references the parent page by its DEVELOPERDOCS_ID.
  • Default is empty: the line is missing entirely.
  • sorting_priority: <integer>
  • Optional. Default is 0 (line missing).
  • Used to order siblings in the left sidebar: higher values appear higher.
  • If priorities are equal, order is alphabetical ascending by title.
  • Implementation detail: the WordPress menu_order field is set to -sorting_priority.

Pipeline

1. Authoring (local)

  • Developers edit Markdown pages in ./docs/devdocs/*.md.
  • Each page contains all page information needed for publishing (at minimum: stable id, title, body; and any ordering/parent data the build requires).

2. Build artifacts (local or server)

  • A Python build script reads ./docs/devdocs/*.md.
  • For each page it:
  • Parses the stable id from the source file.
  • Derives the WordPress-relevant metadata (title, slug, parent id, menu order, etc.).
  • Converts Markdown to the HTML payload to be stored in WordPress.
  • Computes a content hash (and optionally a metadata hash).
  • Writes one generated artifact file per page, named by the hash.
  • The script also writes a single index file (manifest) that lists the complete expected set of pages.

3. Sync to server

  • The build outputs are placed under /var/www/devdocs/ (including the manifest and per-page hash artifacts).
  • The project sync pushes these files to the server.

4. WordPress ingestion (plugin)

  • A WordPress plugin is triggered to ingest DevDocs from /var/www/devdocs/.
  • The plugin:
  • Loads the manifest as the source of truth for which pages must exist.
  • Permanently deletes WordPress pages whose stable id is no longer present in the manifest.
  • Creates pages whose stable id is present in the manifest but missing in WordPress.
  • Updates pages whose stable id exists but whose stored hash differs from the manifest/artifact hash.
  • Skips pages whose stable id exists and whose hash matches.

Deletion And Safety

  • Deletions are determined by stable id absence in the manifest, not by hash filenames.
  • Hash filenames must never be treated as identity, because any edit would otherwise appear as delete+create.