---
title: "References document type"
source: https://dev.pageseeder.com/reference/glossary/references_document.html
description: "The references document type is a built-in PSML document that assembles multiple documents into publications using an xref list editor optimized for adding cross-references and organizing document hierarchy."
last_updated: 2026-09-05T17:36:25+10:00
tokens: ~846
---

# References document type

The “references” document type is the default way to assemble multiple PSML documents into a [publication](/reference/glossary/publications.md).

Along with the “default” document type, the *references* document is one of the built-in PSML document types.

## Xref list editor

What distinguishes the references document is a fragment configured to invoke the *xref list* editor. Unlike the standard rich text editor, *xref list* is optimized to quickly add [cross-references](/reference/glossary/cross_reference.md). This makes it well suited to create a collection of links that bind smaller documents into a publication.

## Publication configuration

By default, the xref list editor adds all xrefs at the same level in the document hierarchy. To make a document subordinate, click the angle-right  or chevron-right icons to the right of the xref title.

When working with numbered documents, this preserves the integrity of either heading or paragraph numbering or any xrefs that reference a particular number. This is the reason to stick to the following concepts:

- Always start a document with the first level heading (**H1** or`<heading level="1">` in PSML) and let the references document adjust the heading according to the rest of the publication. Remember that the same file could be included in a different position in a different publication.
- Create documents around a specific topic, so that the documents can be re-used.
- If multiple levels of references documents are used to represent the publication, don't be inconsistent.

> **Tip:** For example, where a publication has six chapters, don't use references documents for chapter 1, chapter 2, and chapter 3, then link the files for chapter 4, chapter 5 and chapter 6 directly to the main publication references document.

> **Note:** References documents can also be used to assemble non-PSML documents such as PDF files. However, since PageSeeder also uses the heading hierarchy in PSML to build the Table of Contents, only the title of the non-PSML documents appear in the TOC. If you include an xref to a PDF document in your references document and publish it as DOCX, PageSeeder replaces the content with a link in the Word file.

## Template

The [template](/reference/glossary/document_template.md) for this default document includes:

- A “title” section with a single [fragment](/psml/elements/element_fragment.md) containing the title heading and any content that is not part of the Table of Contents such as title page.
- An “xrefs” section with an [xref fragment](/psml/elements/element_xref-fragment.md) where you can specify the list of documents to include.
- A TOC marker.

We recommend that the title heading match the document title. It is used for the publication title.

![References document structure](/content/images/glossary/references_document_structure.svg)

```xml
<?xml version="1.0"?>
<!--
  Default PSML references template
-->
<document type="references" level="portable"
          xmlns:t="http://pageseeder.com/psml/template">

  <t:param name="ps.title" default="[Untitled]" />

  <!-- Title -->
  <section id="title">
    <fragment id="1">
      <heading level="1">
    </fragment>
  </section>

  <!-- Table of contents -->
  <toc/>

  <!-- Cross-references -->
  <section id="xrefs">
    <xref-fragment id="2">
  </section>

</document>
```