The publishing pipeline
When you publish a target, Topicary processes every topic through a 4-stage pipeline. Understanding these stages helps you predict how your authored content becomes the published output.
Pipeline stages at a glance
Stage | Input | Output | What happens |
|---|---|---|---|
1. Resolve | Raw topic content with component references | Content with all components expanded inline | Every |
2. Filter | Resolved content with conditional blocks | Content with non-matching conditions removed | Each conditional block is evaluated against the target's condition profile; non-matching blocks are stripped |
3. Replace | Filtered content with variable tokens | Content with all tokens substituted | Each |
4. Render | Fully resolved plain content | Final HTML (web) or PDF | Content is converted to semantic HTML with heading IDs, sanitized output, and structured metadata |
Stage 1: Resolve
The pipeline starts by resolving component references. Every ComponentRef and InlineComponentRef node in the content is replaced with the actual content of the referenced component.
This happens recursively. If a component references another component, that reference is resolved too. The output of this stage is content with no component references remaining, only their expanded content.
Stage 2: Filter
Next, the pipeline evaluates conditional blocks against the target's condition profile. Each ConditionalBlock node specifies a dimension and one or more values (for example, "Audience: Admin").
The target's condition profile specifies which values are active (for example, { "Audience": ["Admin"] }). If a block's values overlap with the profile, the block's content is kept. If not, the entire block is removed.
When the condition profile is empty, all conditional blocks are included regardless of their values.
Example condition profile input:
{
"Audience": ["Admin", "Developer"],
"Platform": ["Linux"],
"Feature": ["SSO", "RBAC"]
}In this example, conditional blocks tagged with Audience: Admin, Audience: Developer, Platform: Linux, Feature: SSO, or Feature: RBAC would be included. Blocks tagged with other values (for example, Platform: Windows or Audience: End User) would be stripped from the output.
Stage 3: Replace
The pipeline then processes variable tokens. Each VariableToken node contains a variable key (for example, product_name). The pipeline looks up the key in the target's variable set and replaces the token with the value.
If the target has variable overrides, those take precedence over the set's values for the specified keys.
If a key is not found in the variable set or overrides, the token renders as the raw key name. The content health system flags it as an undefined variable.
Stage 4: Render
Finally, the resolved, filtered, variable-substituted content is rendered to HTML. For web targets, this produces semantic HTML with heading IDs (for the table of contents), sanitized output (for security), and structured metadata (for search indexing).
For PDF targets, the HTML is rendered into a print-ready template with page breaks, cover pages, and branded headers and footers.
How web publishing runs
For web targets, this content pipeline runs inside a background job when you click Publish or Update. Before the job starts, the target is validated: if any topic has a blocking validation error, publishing is refused and you are directed to the Validation panel to fix it first.
Once validation passes, the background job works through several steps and reports progress: it rebuilds the site, then generates social preview (Open Graph) images, embeddings, AI-readiness (GEO) scores, and the external search index. You can watch the progress and see a clear failure if a step goes wrong, rather than a silent hang.
Publishing is a one-time setup for each target. After the first publish, the live site is served from a cache that refreshes when you publish or update the target (and automatically at least once every 24 hours). Clicking Update regenerates the site and refreshes the cache immediately.
What this means in practice
A published site is served from a cache, so edits to topics, components, variables, or the map structure are not reflected instantly. Cached pages refresh within 24 hours, or you can click Update on the target to publish the latest content immediately.
The 4 stages run in a fixed order: resolve, filter, replace, render. This ordering is intentional: components are resolved before conditions are filtered, so conditional blocks inside components work correctly. Conditions are filtered before variables are replaced, so variable tokens inside excluded blocks are never processed. Variables are replaced before rendering, so the final HTML contains resolved values, not raw tokens.
Processing order matters
The 4 stages run in a fixed order: resolve → filter → replace → render. This means:
Components are resolved before conditions are filtered. If a component contains conditional blocks, those blocks are correctly filtered in stage 2.
Conditions are filtered before variables are replaced. If a conditional block contains variable tokens, those tokens are only replaced if the block passes the filter.
Variables are replaced before rendering. The rendered HTML contains final values, not tokens.
This ordering ensures that all authoring features compose correctly: components can contain conditions, conditions can contain variables, and the output is always consistent.
Because publishing produces a snapshot, you can safely experiment with condition profiles and variable sets without affecting live sites. Create a new target with different settings, publish it, and compare the output before updating your primary target.
See also
Publish a web site: step-by-step guide to creating a target and running the pipeline
Conditions versus variables: understand when to use conditions (stage 2) versus variables (stage 3)
How component reuse works: how components are resolved in stage 1 of the pipeline
Publication target settings: configure condition profiles and variable sets that drive the pipeline