Skip to main content


A-Z glossary of PageSeeder concepts

References document type

The “references” document type is the default way to assemble multiple PSML documents into a publication.

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

What distinguishes the references document is a fragment configured to invoke the xreflist editor. Unlike the standard rich text editor, xreflist is optimized to quickly add cross-references. This makes it well suited to create a collection of links that bind smaller documents into a publication.

By default, the xreflist editor adds all xrefs at the same level in the document hierarchy. To make a document subordinate, click the  icon 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.

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.

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.


The template for this default document includes:

  • A “title” section with a single fragment 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 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

<?xml version="1.0"?>
  Default PSML references template
<document type="references" level="portable"

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

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

  <!-- Table of contents -->

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


Created on , last edited on