How component reuse works

Component reuse is the foundation of single-source authoring: write a piece of content once, reference it from multiple Create and manage topics, and update it in one place to update everywhere.

The problem with copy-paste #

When the same content appears in multiple topics (a support contact block, a security disclaimer, a setup prerequisite), copy-pasting creates multiple independent copies. When the information changes, you need to find and update every copy. In practice, copies get missed, and your documentation drifts out of sync.

Components as single-source blocks #

In Topicary, a component is a named, reusable content fragment stored independently from any topic. Topics do not contain the component's content. They contain a reference to it.

The distinction matters:

• Copy-paste: Topic A and Topic B each have their own copy of the text. Changing one does not affect the other.

• Component reference: Topic A and Topic B both point to the same component. The component holds the text. Changing the component changes what both topics display.

Live references #

Component references are live, not snapshots. When you view a topic in the editor, component references render the current content of the source component. There is no "sync" step or "pull latest" action. The reference always reflects the source.

Impact awareness #

Because components can be referenced from dozens of topics, Topicary provides impact signals:

• Reference counts on the Components page, and the Where Used panel inside each component, show how many topics (and exactly which topics) reference a component

• Deletion warnings confirm that referencing topics will show broken references before you delete a component

• Find and fix orphaned components flags components with zero references; these are not being used and may be candidates for cleanup

Proactive extraction #

Topicary's editor automatically analyzes your content as you write. When it detects a paragraph that closely matches content in two or more other topics (using embedding similarity), it highlights the passage and suggests extracting it as a reusable component. This helps you identify reuse opportunities you might otherwise miss.

When to use components #

Components work best for content that is:

• Identical across locations: the exact same text, not similar text

• Likely to change: content that is static does not benefit much from single-sourcing

• Used in 3 or more places: two locations might not justify the indirection; 3 or more almost certainly do

Common examples: legal disclaimers, support contact blocks, prerequisite lists, standard warnings, version-specific notes, and API authentication boilerplate.

When not to use components #

If content is similar but not identical across locations, components are not the right tool. Use Create conditional content blocks or Create variable sets for content that varies by audience or context. Use components only for content that should be exactly the same everywhere it appears.

See also #

• Create reusable components: step-by-step instructions for creating components

• Insert component references: how to embed components into your topics

• Conditions versus variables: when to use conditions or variables instead of components

• The topic-map-publication model: how components fit into the broader publishing architecture