Transclusions and embedded xrefs
Key point: Transclusions are displayed in the user interface, embedded xrefs only after publishing.

Both are types of xref, but the essential difference between an embedded xref and a transclusion is when the referenced content is included in the document.

Transcluded content is automatically included in the source document. It is therefore immediately available in the user interface when users view the document. Embedded content is only included when the content is published. Until the content is published, an embedded xref is shown as a regular link in the user interface.

When to use transclusions

Transclusions are designed to avoid duplication and let you reuse the same piece of content. Use transclusions when you need to maintain a reusable piece of content in a location that is different from the document it appears in. Any update to the transcluded content is reflected in all the documents.

For example, a copyright statement or short biography can be integrated into multiple documents.

Usually, transclusions point to fragments rather than whole documents. But it’s okay to transclude an entire document.

Don’t use too many transclusions!

  • For end-users, it can be confusing when the same content appears in multiple places – consider reorganizing your content if that is the case.
  • For authors, too many transclusions might be less convenient as they cannot edit the transclusions in place.
  • The PageSeeder search indexes each use of the transclusion as if it were part of the content, so it appears multiple times in searches.
  • Public search tools might also detect as duplicate content, which might affect your ranking or make it harder for users to find what they’re looking for.
  • A large number of transclusions might also affect the performance of the system. 

When to use embedded xrefs

Embedded xrefs are primarily designed to aggregate content for publications. They are designed to let you split your documents so that they can be viewed, edited, and organized more efficiently. They can also be used to avoid duplicating content by embedding the same document in different publications.

Usually, embedded xrefs point to whole documents. Although it’s possible to embed a document fragment, it’s generally best avoided.

Use embedded xrefs in references documents to assemble a publication, or in a document type that has been designed for a similar purpose.

  • Avoid using an embedded xref within a fragment – because the xref is not replaced until after the content is published, it’s not as clear for author and readers what content is to be included.
  • Avoid referencing the same document multiple times in the same publication – the same content appears multiple times but with different numbering, which can be very confusing for readers.

Summary of differences