Skip to main content

Publish Bridge

SCS sends the article half of the Markdown file to WordPress. SCS creates or updates drafts and reads WordPress status back; WordPress is also the visual review surface.

The bridge supports draft creation, live publishing, scheduling, and desired-state application from CSV/front matter. Pending, scheduled, and published transitions require an approved QA snapshot. A live post is never converted back to a draft.

Commands​

scs wp inspect --workspace bs --site opshell
scs wp draft --workspace bs --pid FS-0001 --dry-run
scs wp draft --workspace bs --pid FS-0001
scs wp publish now --workspace bs --pid FS-0001
scs wp publish 2026/12/31 --workspace bs --pid FS-0001
scs wp publish data/bs/md/FS-0001--balance-sheet-basics.md
scs wp status --workspace bs --pid FS-0001
scs wp diff --ws bs --pid FS-0001
scs wp pull-content --ws bs --pid FS-0001
scs wp diff data/bs/md/FS-0001--balance-sheet-basics.md
scs wp pull-content data/bs/md/FS-0001--balance-sheet-basics.md
scs qa open  --workspace bs --pid FS-0001

The publish and QA commands can also target an article by its Markdown file path. SCS resolves the workspace and PID from the registered article path; the path must be inside the SCS repository and belong to a workspace keyword record.

--dry-run is fully local: it builds and prints the payload without calling WordPress. Use it before every real write.

Compare or retrieve WordPress edits​

scs wp diff accepts either --ws WORKSPACE --pid PID or a registered article Markdown path, such as scs wp diff data/bs/md/FS-0001--balance-sheet-basics.md. It fetches the post body and prints a unified diff against the local Markdown body (front matter is excluded). It is read-only; exit status 1 means differences were found, while 0 means the bodies match.

scs wp pull-content supports the same workspace/PID or article-path forms and saves the current WordPress body as a separate *.wordpress-<post-id>.md review snapshot beside the source article. It refuses to overwrite an existing snapshot and never changes the SCS source Markdown or WordPress post. Review the snapshot and merge desired changes into the authoritative article manually; do not treat it as an automatic merge.

What gets written​

  • post_title from the keyword title
  • post_content converted from the article half (after <!-- scs:article -->) to Gutenberg blocks; the brief half is never published
  • post_status from the requested mode: draft, pending, publish, or future
  • post_name from publishing.slug when set
  • author from publishing.wp_author_id
  • category by name, tags from publishing.wp_tag
  • content_format taxonomy from publishing.wp_content_format
  • webboulder_authority_topic by term name or slug
  • SEOPress title and description
  • ACF primary_keyword, semantic_tags, content_type, pillar_parent, cluster_parent, hub_parent
  • post meta scs_pid, scs_workspace, _scs_source_path, _scs_synced_at

scs_pid is the idempotency key. A second publish updates the same draft; it does not create a duplicate.

Sitemaps​

The publish bridge does not write sitemap XML. SEOPress generates the sitemap automatically from the site's published content, so a draft never appears in it and nothing needs to be rebuilt after scs publish. Verification steps are in XML Sitemaps.

Use the SCS PID scheme in Markdown:

See [the current ratio guide](pid:FS-0003) for the next step.

SCS resolves the PID through publishing.csv and requires a wp_link. Publish the target first, or fill the link manually.

Block conversion​

The pilot converter supports:

  • headings H1–H6
  • paragraphs, bold, italic, inline code, links
  • unordered and ordered lists
  • tables
  • fenced code blocks
  • Mermaid fences (rendered by the site plugin)
  • blockquotes
  • images
  • :::tip / :::note / :::warning admonitions
  • horizontal rules

It is intentionally a subset. If a block renders badly, fix the Markdown or add a converter case; do not paste raw HTML into the article.

Safety rules​

  • Only the article half is sent; the brief stays local.
  • A published post is never converted back to draft, pending, or scheduled.
  • scs wp publish now and scs wp publish <date> require an approved QA snapshot.
  • A post that SCS did not create is not overwritten without --force.
  • Desired state can be stored in publishing.csv or article front matter and applied with scs wp publish <article.md>.
  • The draft is keyed by scs_pid; title matching is not used.
  • WordPress is the review surface; SCS stores a QA snapshot for reporting only.
  • Secrets and credentials stay in the server configuration, never in Markdown or CSV.

Current limitations​

  • Featured images are recorded in publishing.featured_image but not uploaded by the pilot.
  • Optional JSON-LD lives in data/<workspace>/schemas/<pid>.json, referenced by publishing.schema_file. Use scs schema init/check to create, link, and validate a PID-keyed file; init moves eligible early records to Writing, and replace all starter placeholders before validation. Publishing stores referenced data in _scs_jsonld_schema post-meta but does not inject a JSON-LD script; a site-level output integration must be configured without duplicating the SEO plugin's schema. When populated, publishing.schema_type must match the JSON-LD @type.
  • Category and authority-topic terms must already exist; missing terms are skipped and should be fixed before publishing.
  • The converter targets the opshell plugin stack; other sites may need block adjustments.
warning

Run scs publish --dry-run and inspect the block preview before the first write to a new site. ACF and taxonomy mappings differ between sites.