Skip to main content


Configuration manual for PageSeeder

Xref config

For writers that create a lot of links, customizing the xref-config improves consistency and productivity by pre-configuring cross reference (xrefs) targets into the user interface. This saves writers from having to set values with each link.

Like other configurations, the xref-config exists at the project-level, so the file is available at:


It is also available through the Edit XRef configs button at the top of the administration Template configuration page.

xref-config uses the following structure:

  <xref-config name="[name of config]"
               title="[title in UI]" >
    <xref ... />
    <target .../>
    <autosuggest .../>

  <xref-config ...>

There is no limit to the number of <xref-config> elements – the only required attribute or element is @name.

To create xrefs to any document (including non-PSML) use the following: 

<xref-config ...>
  <target filters="pstype:document" />

The same code can be used in the editor-config.xml.

To restrict this to PDF files for example change the filter to:


To reference multiple subtypes, for example PDF and image files use:



Three aspects of the editor are configurable:

  • Attributes of the xref.
  • Where to look for the target document, and
  • Auto-suggest search options to find a target document.

None of these options are required.


The attributes on the <xref> element are described in the following table. The creation of an xref from a definition in the xref-config forces the attributes onto the link. The only exception is the @optionallabels attribute. That attribute gives the user an opportunity to select xref labels.

AttributeDescriptionDefault value

What title is used to represent the link in the document.

Possible values are:

  • document (the title of the target document).
  • document+fragment (the title of the document and the title of the section).
  • document+manual (the title of the document and manually entered text).
  • manual, template (see @title attribute below).
fragThe ID of the target fragment in the target document (a value of default points to the entire document).
labelsComma-separated list of mandatory xref labels added to the cross-reference
optionallabelsComma-separated list of xref labels for users to select from

Manually entered text when the value of @display is:

  • manual
  • document+manual, or
  • template – (can include placeholder tokens that resolve to dynamic data, see Cross-reference display).

The cross-reference type that determines how to process the xref, possible values are:

  • none
  • alternate
  • transclude (usable with <blockxref> only).
  • embed (usable with <blockxref> only), and
  • math (usable with <xref> only).
levelAn incremental value to demote the heading levels of a target document when processing the xref. Allowable values are [0-5] – 0 leaves the level of the target headings unchanged after the xref has been resolved.0
reverselinkBoolean flag to specify a two-way xref. Possible values are true or false.true
reversetitleThe reverse xref title. In other words, the title to display at the target end of the link, not the source.


<xref display="manual"
      title="My Link Title"
      reverselink="false" />

Target document

The target document is defined using attributes on the <target> element as follows:

AttributeDescriptionDefault value
documenttypeA comma-separated list of document types allowed for the target document.
groupThe project and group to search for target documents (for example, acme-specs)[current group]

See notes following this table.

The document search path relative to the group.

  • Use “.” or “..” for a path relative to the current document.
  • To search an absolute folder path start  with “/”.
  • The asterisk “ *” substitutes for any path segment except where the path is relative to the current document. In other words, any value that starts with “.” or “...

A comma-separated list of filters (field:value) to focus search results. For example:


filters also apply to the xref browse-document page.

Adding a plus sign before pslabel allows users to select additional labels (v5 UI only). For example:



OBSOLETE as of PageSeeder v6, this functionality is no longer supported. Allowable values for creating a new target document.

  • none – do not allow the creation of a target document.
  • create – allow the creation of a target document.
  • edit – create, and then open to edit, a new target document.

If the xref target is in the current document, a value of true  overrides the auto-suggest configuration. This sets the value on @new as follows:


  • Specifiying any target attributes will stop files from being listed under browse on the xref dialog.
  • When using an inline label as a filter, remember that they are case-sensitive. (see Index for more information).

Folder attribute examples

Following are examples of specifying a search location starting from the following path and filename:


in a group with the name:


For the @folder attribute, use of the wildcard character “*” in any path segment re-orients the search to the equivalent folder in the path of the current document.

If the wildcard does not match a segment in the current path, the system displays an alert message and prevents the xref-config from creating or editing a link.

@folder valueactual location
images/*[xref cannot be created or edited]


<target folder="documents/*" filters="psstatus:Approved" />

Auto-suggest configuration

This uses the same search as the search box. It is configured through the following attributes on the <autosuggest> element:

AttributeDescriptionDefault value
questionfieldsA comma-separated list of index fields to searchpstitle,psfilename, psdocid,psid

A comma-separated list of fields to display in the search results.

pstitle and psid are always displayed. To include the path, add these fields – psfolder, psfilename


Sample config

  <xref-config name="footnote" title="Footnote" >
    <xref display="template" title="f{fragment}" type="none" />
    <target documenttype="footnotes" folder="." />
  <xref-config name="definition" title="Definition">
    <xref display="template" title="{heading}" type="none" />
    <target documenttype="definitions" folder="." />
  <xref-config name="para" title="Paragraph" >
    <xref display="template"
          type="none" />
  <xref-config name="internal-para" title="Internal paragraph" >
    <xref display="template" title="{prefix}" type="none" />
    <target this="true" />
  <xref-config name="numbered-heading" title="Numbered heading" >
    <xref display="template"
          title="{prefix} {heading}"
          type="none" />
  <xref-config name="asciimath" title="AsciiMath">
    <xref display="document"
          type="math" />
    <target documenttype="asciimath" />
Created on , last edited on