The publishing pipeline
When you publish a target, Topicary processes every topic through a four-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 (e.g., "Audience: Admin").
The target's condition profile specifies which values are active (e.g., { "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 (e.g., 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 (e.g., 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 isn't found in the variable set or overrides, the token renders as the raw key name — and 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.
What this means in practice
Publishing creates a snapshot, not a live connection. Edits to topics, components, variables, or the map structure are not automatically reflected on the published site. You must click Publish again to regenerate the site with the latest content.
The four 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 four 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 vs. 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