This page describes the current intended pipeline for publishing DevDocs pages into WordPress.<\/p>\n
.\/docs\/devdocs\/<\/code> (source of truth).<\/li>\n- Detect changes cheaply and deterministically.<\/li>\n
- Ensure WordPress ends up exactly matching the DevDocs set (add\/update\/delete) with minimal work.<\/li>\n<\/ul>\n
Key Concepts<\/h2>\n\n- Stable page identity: every DevDocs page must contain a stable identifier (
DEVELOPERDOCS_ID<\/code>). This identifier is the primary key for reconciliation in WordPress.<\/li>\n- Hash artifacts: hashes are used to detect changes, not to define identity.<\/li>\n
- One artifact per page: the build produces one generated artifact file per page, named by its hash, plus an index\/manifest.<\/li>\n<\/ul>\n
Page Header Contract<\/h2>\n\nDEVELOPERDOCS_ID: dd_id_<10 lowercase alphanumeric><\/code><\/li>\n- Mandatory for every DevDocs page.<\/li>\n
- Auto-generated on first page creation, then stable forever.<\/li>\n
- The alphanumeric string is always lowercase.<\/li>\n
PARENT_DEVELOPERDOCS_ID: dd_id_<10 lowercase alphanumeric><\/code><\/li>\n- Optional.<\/li>\n
- If present, it references the parent page by its
DEVELOPERDOCS_ID<\/code>.<\/li>\n- Default is empty: the line is missing entirely.<\/li>\n
sorting_priority: <integer><\/code><\/li>\n- Optional. Default is
0<\/code> (line missing).<\/li>\n- Used to order siblings in the left sidebar: higher values appear higher.<\/li>\n
- If priorities are equal, order is alphabetical ascending by title.<\/li>\n
- Implementation detail: the WordPress
menu_order<\/code> field is set to -sorting_priority<\/code>.<\/li>\n<\/ul>\nPipeline<\/h2>\n
1. Authoring (local)<\/p>\n
\n- Developers edit Markdown pages in
.\/docs\/devdocs\/*.md<\/code>.<\/li>\n- Each page contains all page information needed for publishing (at minimum: stable id, title, body; and any ordering\/parent data the build requires).<\/li>\n<\/ul>\n
2. Build artifacts (local or server)<\/p>\n
\n- A Python build script reads
.\/docs\/devdocs\/*.md<\/code>.<\/li>\n- For each page it:<\/li>\n
- Parses the stable id from the source file.<\/li>\n
- Derives the WordPress-relevant metadata (title, slug, parent id, menu order, etc.).<\/li>\n
- Converts Markdown to the HTML payload to be stored in WordPress.<\/li>\n
- Computes a content hash (and optionally a metadata hash).<\/li>\n
- Writes one generated artifact file per page, named by the hash.<\/li>\n
- The script also writes a single index file (manifest) that lists the complete expected set of pages.<\/li>\n<\/ul>\n
3. Sync to server<\/p>\n
\n- The build outputs are placed under
\/var\/www\/devdocs\/<\/code> (including the manifest and per-page hash artifacts).<\/li>\n- The project sync pushes these files to the server.<\/li>\n<\/ul>\n
4. WordPress ingestion (plugin)<\/p>\n
\n- A WordPress plugin is triggered to ingest DevDocs from
\/var\/www\/devdocs\/<\/code>.<\/li>\n- The plugin:<\/li>\n
- Loads the manifest as the source of truth for which pages must exist.<\/li>\n
- Permanently deletes WordPress pages whose stable id is no longer present in the manifest.<\/li>\n
- Creates pages whose stable id is present in the manifest but missing in WordPress.<\/li>\n
- Updates pages whose stable id exists but whose stored hash differs from the manifest\/artifact hash.<\/li>\n
- Skips pages whose stable id exists and whose hash matches.<\/li>\n<\/ul>\n
Deletion And Safety<\/h2>\n\n- Deletions are determined by stable id absence in the manifest, not by hash filenames.<\/li>\n
- Hash filenames must never be treated as identity, because any edit would otherwise appear as delete+create.<\/li>\n<\/ul>\n
DeveloperDoc ID: dd_id_h9qvuokrif<\/p>\n","protected":false},"excerpt":{"rendered":"
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 […]<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":1357,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"doc_category":[],"doc_layer":[26],"class_list":["post-1309","page","type-page","status-publish","hentry","layer-dd_id_d920cc6a97"],"_links":{"self":[{"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=\/wp\/v2\/pages\/1309","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=1309"}],"version-history":[{"count":5,"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=\/wp\/v2\/pages\/1309\/revisions"}],"predecessor-version":[{"id":3826,"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=\/wp\/v2\/pages\/1309\/revisions\/3826"}],"up":[{"embeddable":true,"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=\/wp\/v2\/pages\/1357"}],"wp:attachment":[{"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=1309"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=%2Fwp%2Fv2%2Fdoc_category&post=1309"},{"taxonomy":"doc_layer","embeddable":true,"href":"https:\/\/docs.ai.drawconclusions.org\/index.php?rest_route=%2Fwp%2Fv2%2Fdoc_layer&post=1309"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}