Troubleshooting
Common issues and how to resolve them.
Quick lookup
Symptom | Section |
|---|---|
Changes not showing on published site | |
PDF looks different from web | |
Version selector missing | |
Can't delete a component | |
Component outdated on site | |
Conditioned content missing | |
Variable tokens show key name | |
Can't import files | |
Images missing after import | |
Formatting lost in import | |
Nested lists flattened | |
Can't add topics | |
Can't add team members | |
Analytics not visible | |
AI widget not showing | |
Can't delete map version | |
Lost targets after version delete | |
Password reset | |
Search returns no results |
Publishing
My changes aren't showing on the published site
Published sites are a snapshot of your content at the time you click Publish. After editing topics, conditions, variables, or map structure, republish the target to update the live site.
Topicary does not auto-publish. Every change — content edits, condition updates, variable changes, map reordering — requires a manual republish to go live. This is by design: it gives you a controlled release workflow.
My PDF looks different from the web output
PDF output uses print-specific CSS. Interactive elements (code tabs, search, dark mode) don't apply to PDF. Tables, images, and callouts may render with different spacing.
The version selector doesn't appear on my published site
The version selector only shows when two or more versions of the same map each have a published target. Publish at least two versions to enable it.
Components
I can't delete a component
A component can't be deleted while topics reference it. Check the where-used count on the Components page to see which topics reference it. Remove all references first, then delete the component.
My component shows outdated content on the published site
Component references are live in the editor — you always see current content. Published sites use a snapshot from the last publish. Republish to pick up component changes.
Conditions and variables
Conditioned content isn't appearing in my published output
Check two things: (1) the content block has the correct condition applied in the editor — open condition preview to verify, and (2) the publication target's condition profile includes the matching value. A block conditioned on "Audience: Admin" only appears in targets where the condition profile includes Audience = Admin.
Use the condition preview in the editor to see exactly which blocks are visible for each condition profile. This lets you verify content visibility without publishing.
Variable tokens show the key name instead of the value
The publication target needs a variable set assigned. Go to the map editor, open the target settings, and select a variable set that defines the key used in the token.
Import
I can't import files
Import requires a Pro, Team, or Business plan. Free plans don't include import.
Images are missing after import
Import preserves image references as URLs but doesn't upload local image files. After importing, re-upload images using the image insert tool in the editor.
My import lost formatting
Complex formatting from the source tool may not transfer. Confluence macros (Jira links, dynamic content blocks, custom macros), Flare conditional sections, Word tracked changes, and embedded objects are simplified or removed during import.
Source format | What transfers | What is lost or simplified |
|---|---|---|
Confluence | Headings, paragraphs, lists, tables, images (as URLs), basic formatting | Macros (Jira links, dynamic content, custom), page trees, comments |
MadCap Flare | Topics, TOC structure, basic formatting, snippets | Conditional sections, targets, stylesheets, build logic |
Microsoft Word | Headings, paragraphs, lists, tables, basic formatting | Tracked changes, comments, embedded objects, complex styles |
Markdown | Full content with formatting | None (Markdown is the closest match to the internal format) |
Nested lists are flattened after import
Deeply nested lists from Confluence or Word may lose levels during conversion. Review imported topics and manually adjust list indentation where needed.
Plan limits
I can't add more topics
The Free plan allows up to 10 topics. Upgrade to Pro for unlimited topics.
I can't add more team members
Author limits depend on your plan: 1 on Free, 3 on Pro, 10 on Team, unlimited on Business.
I don't see analytics
Analytics are available on Team and Business plans.
The AI chat widget isn't showing on my published site
AI features (embed widget, AI search, Ask endpoint) require a Pro, Team, or Business plan. Free plan published sites don't include the AI widget.
Maps and versions
I can't delete a map version
The original (root) version cannot be deleted. Only versions created after the original can be removed.
I deleted a version and lost my publication targets
Deleting a map version permanently removes all publication targets associated with it. This action cannot be undone. To preserve published sites, unpublish targets before deleting the version.
Account
How do I reset my password?
Go to the login page and click "Forgot password." Enter your email address to receive a reset link.
Why did search return no results on my published site?
Search indexes topic titles and body text. Try shorter or broader queries. Check for typos. If readers consistently search for terms that return nothing, the content gaps dashboard highlights these zero-result queries so you can create or rename topics to match.
See also
Publish a web site — publishing workflow referenced in several troubleshooting scenarios
Import formats — supported formats and known limitations when importing content
Plans and limits — plan-related limits that cause many of the issues listed above
Content health indicators — automated checks that can surface broken references and undefined variables before publishing