Skip to main content
Last updated: 12 Sep 2025

content-block-manager: How embedding works

Content Block Embedding is mainly handled in the Publishing API, with some shared code in the Content Block Tools gem detailed in the diagram and steps below:

flowchart-elk TD;
  subgraph Publishing App
      A(Save draft)
      L(Publish Saved Draft)
  end

  subgraph Content Block Manager
      P[Content Block updated]
  end

  subgraph Publishing API
    A --> B(Host Document sent to PUT content endpoint)
    B --> C(Embedded Content Finder Service is called)
    C --> D(Iterates through details to find embedded content blocks)
    D --> E(Content Block Tools finds all Content Block References)
    E --> F(References passed back to Service)
    F --> G{Live editions found?}
    G -- Yes --> H(Create embed link for Host Document)
    H --> I(Send Downstream to DownstreamDraftJob)
    I --> J(DownstreamPayload calls EditionPresenter)
    J --> K(ContentEmbedPresenter replaces embed codes with relevant content)

    L --> M(DownstreamDraftJob and DownstreamLiveJob executed)
    M --> J

    P --> Q
    Q(Publishing API calls send_downstream to DownstreamLiveJob) --> R(DownstreamLiveJob calls HostContentUpdateJob)
    R --> S(Fetch all linked documents)
    S --> T(Republish linked documents)
    T --> J
    T --> U(Create event to record republished documents)
  end

Adding embed code to a host document

Saving a draft

When saving the changes to a Host Document, we trigger an update of the draft Content Store:

  1. The publishing app updates the Host Document via the PUT content endpoint in Publishing API

  2. The Embedded Content Finder Service is called.

  3. The service then iterates through the details of an Edition to pass it to the Content Block Tools to find any embedded content blocks

  4. Content Block Tools finds all the Content Block References and passes them back to the Service.

  5. If live editions are found of the references, then a link of type embed is created for the Host Document with the content_id of the embedded block.

  6. Once the links have been created, the Publishing API calls send_downstream to send to the DownstreamDraftJob.

  7. The Downstream job then calls, via DownstreamPayload, an EditionPresenter, which eventually gets to the ContentEmbedPresenter

  8. The ContentEmbedPresenter then looks for any embed Links and replaces any embed codes with the relevant content for the latest live edition of the Block.

Publishing a saved draft

Once the draft is saved, the publishing app makes a subsequent call to the Publishing API to publish:

  1. The Publishing API calls send_downstream to send to the DownstreamDraftJob and DownstreamLiveJob.

  2. The Downstream jobs then call, via DownstreamPayload, an EditionPresenter, which eventually gets to the ContentEmbedPresenter

  3. The ContentEmbedPresenter then looks for any embed Links and replaces any embed codes with the relevant content for the latest live edition of the Block.

Updating a content block

When a change to a content block is published, we trigger the following process in Publishing API:

  1. The Publishing API calls send_downstream to send to the DownstreamLiveJob.

  2. The Downstream job then calls the HostContentUpdateJob (which is a subclass of DependencyResolutionJob

  3. The Host Content Update job then fetches all the linked documents

  4. Each of the linked documents is then republished. This kicks off the process outlined in Publishing a saved draft to re-render the page and send the new version to the Content Store.

  5. The Host Content Update job also creates an Event to record that the linked document was republished by a change to a content block. This can be used by publishing apps to track changes to a content block. See tracking when a content block changes for more.