---
title: "Xref config"
source: https://dev.pageseeder.com/guide/configuration/psml/psml_xref_config.html
description: "Configuration guide for customizing cross-reference (xref) targets in PageSeeder. Explains XML structure, attributes, target document settings, and auto-suggest options to improve writer productivity and consistency."
last_updated: 2026-09-08T11:52:34+10:00
tokens: ~2162
---

# Xref config

For writers that create a lot of links, customizing the `xref-config` improves consistency and productivity by pre-configuring [cross reference](/reference/glossary/cross_reference.md) (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:

`template/[project]/config/xref-config.xml`

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

`xref-config` uses the following structure:

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

  <xref-config ...>
             ...
  </xref-config>
  ...
</xref-configs>
```

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

> **Note:** To create xrefs to any document (including non-PSML) use the following: ```xml <xref-config ...> <target filters="pstype:document" /> </xref-config> ``` The same code can be used in the `editor-config.xml`. To restrict this to PDF files, for example, change the filter to: `filters="pstype:document,pssubtype:pdf"` To reference multiple subtypes, for example, PDF and image files, use: `filters="pstype:document,pssubtype:pdf,pssubtype:image"`

## Options

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.

### Attributes

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.

| Attribute | Description | Default value |
| --- | --- | --- |
| `display` | 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). |  |
| `frag` | The ID of the target fragment in the target document (a value of `default` points to the entire document). |  |
| `labels` | Comma-separated list of mandatory xref labels added to the cross-reference |  |
| `optionallabels` | Comma-separated list of xref labels for users to select from |  |
| `title` | 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](/psml/datatypes/pageseeder_datatypes.md)). |  |
| `type` | 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). | `embed` |
| `level` | An 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` |
| `reverselink` | Boolean flag to specify a two-way xref. Possible values are `true` or `false`. | `true` |
| `reversetitle` | The reverse xref title. In other words, the title to display at the target end of the link, not the source. |  |

Example:

```xml
<xref display="manual"
      title="My Link Title"
      labels="label1,label2"
      reverselink="false" />
```

### Target document

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

| Attribute | Description | Default value |
| --- | --- | --- |
| `documenttype` | A comma-separated list of document types allowed for the target document. |  |
| `group` | The project and group to search for target documents (for example, `acme-specs`) | `[current group]` |
| `folder` | *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 “`..`”**.** |  |
| `filters` | A comma-separated list of `filters` (`field:value`) to focus search results. For example: `pslabel:car,pssubtype:image` `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: `+pslabel:car` |  |
| `new` | ***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. | `create` |
| `this` | 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: `@new="none"` | `false` |

> **Note:** - Specifying any target attributes will stop files from being listed under browse on the xref dialog. - When using an [inline label](/reference/glossary/inline_label.md) as a filter, remember that they are case-sensitive. (*see* [Index](/reference/index.md) for more information).

#### Folder attribute examples

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

`/ps/acme/specs/documents/folder/myfile.psml`

in a group with the name:

`acme-specs```

> **Note:** 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` value | actual location |
| --- | --- |
| `documents/*` | `/ps/acme/specs/documents/folder` |
| `*/*` | `/ps/acme/specs/documents/folder` |
| `*` | `/ps/acme/specs/documents` |
| `images/*` | `[xref cannot be created or edited]` |
| `documents` | `/ps/acme/specs/documents` |
| `/ps/acme/specs/documents` | `/ps/acme/specs/documents` |
| `.` | `/ps/acme/specs/documents/folder` |
| `..` | `/ps/acme/specs/documents` |
| `./assets` | `/ps/acme/specs/document/folder/assets` |
| `../assets` | `/ps/acme/specs/document/assets` |
| `../../assets` | `/ps/acme/specs/assets` |

Example:

```xml
<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:

| Attribute | Description | Default value |
| --- | --- | --- |
| `questionfields` | A comma-separated list of index fields to search | `pstitle,psfilename, psdocid,psid` |
| `displayfields` | 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` | `psfolder,psfilename` |

## Sample config

```xml
<xref-configs>
  <xref-config name="footnote" title="Footnote" >
    <xref display="template" title="f{fragment}" type="alternate" />
    <target documenttype="footnotes" folder="." />
  </xref-config>
  <xref-config name="definition" title="Definition">
    <xref display="template" title="{heading}" type="none" />
    <target documenttype="definitions" folder="." />
  </xref-config>
  <xref-config name="para" title="Paragraph" >
    <xref display="template"
          title="{parentnumber}{prefix}"
          type="none" />
  </xref-config>
  <xref-config name="internal-para" title="Internal paragraph" >
    <xref display="template" title="{prefix}" type="none" />
    <target this="true" />
  </xref-config>
  <xref-config name="numbered-heading" title="Numbered heading" >
    <xref display="template"
          title="{prefix} {heading}"
          type="none" />
  </xref-config>
  <xref-config name="asciimath" title="AsciiMath">
    <xref display="document"
          frag="media"
          type="math" />
    <target documenttype="asciimath" />
  </xref-config>
</xref-configs>
```