A complete reference of PageSeeder's markup language PSML



A block level cross reference.

This type of cross reference is usually used to insert content from another document using the "embed" or "transclude" type. Or it can be used to build table of contents.


The @frag attribute is required plus at least one of the following:

  • @href
  • @docid
  • @uriid.

This element's content text (displayed as the link title) is generated. Therefore the content is only INFORMATIONAL and is discarded by the upload process. The two exception to this are:

  • when @display='manual' and @title is missing or empty, then @title takes the value of the content;
  • when the cross reference can not be resolved, then the content is retained.

For these reasons it is a good practice to include some text in the element's content.

It is the only type of link allowed inside an <xref-fragment>.

When the PSML is processed a block XRef may contain the content of the targeted document or fragment.


There is a limit on the maximum number of cross-references including both inline <xref> and block <blockxref> that can be in a single document. Though the hard limit is higher it is recommended not have more than 1,000 xrefs in a document.

Usage context

Element categoryblock content
PSML levelportable
Permitted contenttext *
Permitted parent<fragment> <xref-fragment>...
HTML equivalent<a>
OpenXML equivalent
PSStandard equivalent <blockXref>


 * In PSML processed level the content can be <document>, <locator>, <fragment>, <xref-fragment>, <properties-fragment> or <media-fragment>.


This element includes the following attributes

configxref-confignoThe configuration name for this XRef
displayxref-displaynoDefines format of target link text
dociddocument-idnoThe document ID of the target 
documenttypedocument-typenoThe target document's type.
externalbooleannoIf "true" the target is a URL (external URI).
fragfragment-idyesThe fragment ID of the target
hrefxs:stringnoPath to the target document
idxs:longnoXLink ID of the cross-reference 
labelslabel-listnoA list of XRef labels
levelxref-levelnoThe level of heading the target document should start at
mediatypexs:stringnoThe target document media type
reverselinkbooleannoA flag indicating if the link is bidirectional
reversetitlexs:stringnoThe title in the reverse direction
reversetypexref-typenoAlways "none"
reversefragfragment-idnoThe fragment ID on the source
titlexs:stringnoThe manually entered title
typexref-typenoType for link processing (default is "embed"). 
unresolvedboolean noIf "true" the target document could not be resolved.
uriidxs:longnoURI ID of the target document
urititlexs:stringnoTitle of the target URI (generated)
urilabelslabel-listnoLabels of the target URI (generated)


Defines how the target link text of this cross-reference is displayed (Default is "document").

 The following values are allowed:

  • document  [document title];
  • document+manual  [document title]: [manual title];
  • document+fragment  [document title]: [target fragment id];
  • manual  [manual title];
  • template see Cross-reference display.


The document ID of the target.

It overrides the uriid on upload.


The target document's type. INFORMATIONAL - ignored by upload.


If  "true" the target is a URL (external URI). INFORMATIONAL - ignored by upload.


The target fragment ID. When this value is "default" it refers to the entire document.

Also, the value of this attribute may refer to fragments other than PSML fragments.


When uploading this may be a path relative to the current document or an absolute path beginning with / and must be URL encoded. If it is "#" the current document will be the target.

It overrides the docid and uriid on upload.


The ID of the XLink corresponding to this cross-reference. INFORMATIONAL - ignored by upload.


A comma-separated list of XRef labels.


The level that the heading numbering of the target document should start from. 


The mediatype of the target document.

The media type of PSML documents is "application/vnd.pageseeder.psml+xml". INFORMATIONAL - ignored by upload.


A boolean attribute to indicate whether the cross-reference is bidirectional, that is a reverse link. When set to "true" (default), the cross-reference will also appear on the target document as part of its metadata.


The manually entered title to appear on the reverse link.


Type for link processing of reverse link (only "none" is currently supported)


The fragment ID on the source. INFORMATIONAL - ignored by upload.


The manually entered title to appear on the link (only used when @display='manual' or @display='document+manual'). When @display='manual' and @title is missing or empty, then @title takes the value of the element's content text.


The type defines how PageSeeder should process the cross-reference.

The following values are allowed:

  • none  No link processing;
  • alternate  An alternate representations of the current document;
  • embed  Replace this element's content with the document/fragment pointed to when publishing;
  • transclude  Replace this element's content with the document/fragment pointed to when displaying.


The default type for block XRef is "embed" whereas it is "none" for inline XRefs.


If "true" the target document doesn't exist. INFORMATIONAL - ignored by upload.


The URI ID of the target document.

Ignored by upload if on a different PS server.


An informational attribute providing title of the target URI. INFORMATIONAL - ignored by upload.


A comma separated list of labels of the target URI. Introduced in v0.11 of the PSML schema in PageSeeder v5.95. INFORMATIONAL - ignored by upload.


For developers constructing <blockxref> elements, it is useful to remember the server will automatically expand a minimally-expressed link. All that is required is the address of the document and fragment and some content to make the link visible. In other words a link can be as simple as the following:

<blockxref href="filename.psml" frag="default">link title</xref>
<blockxref docid="server-wide_uniqueid" frag="default">link title</xref>
<blockxref uriid="9999" frag="5">link title</xref>

Except for the @uriid, which must be generated by the system, documents containing these minimal links can be uploaded before the other end of the link is available.

When both ends are available, any user with the appropriate rights can go to the Group Manage page under the Admin menu and select the option to Resolve References.

The PageSeeder server will then resolve the <blockxref> element, add the implied attributes and values and create a <reversexref> element at the link destination.


XML Schema

<xs:element name="blockxref">
         <xs:attribute name="id" type="xs:long"/>
         <xs:attribute name="docid" type="document-id"/>
         <xs:attribute name="href" type="xs:string"/>
         <xs:attribute name="uriid" type="xs:long"/>
         <xs:attribute name="frag" type="fragment-id" use="required"/>
         <xs:attribute name="title" type="xs:string"/>
         <xs:attribute name="level" type="xs:integer"/>
         <xs:attribute name="display">
               <xs:restriction base="xs:string">
                  <xs:enumeration value="document" />
                  <xs:enumeration value="document+manual" />
                  <xs:enumeration value="document+fragment" />
                  <xs:enumeration value="manual" />
         <xs:attribute name="type">
               <xs:restriction base="xs:string">
                  <xs:enumeration value="none"/>
                  <xs:enumeration value="alternate"/>
                  <xs:enumeration value="embed"/>
                  <xs:enumeration value="transclude"/>
         <xs:attribute name="labels" type="xs:string"/>
         <xs:attribute name="urititle" type="xs:string"/>
         <xs:attribute name="mediatype" type="xs:string"/>
         <xs:attribute name="documenttype" type="xs:string"/>
         <xs:attribute name="reverselink" type="xs:boolean"/>
         <xs:attribute name="reversetitle" type="xs:string"/>
         <xs:attribute name="reversetype">
               <xs:restriction base="xs:string">
                  <xs:enumeration value="none" />
         <xs:attribute name="reversefrag" type="fragment-id"/> 
         <xs:attribute name="unresolved" type="xs:boolean"/>
         <xs:attribute name="external" type="xs:boolean"/>

Relax Schema

element blockxref {
   attribute id { xs:long }?,
   attribute docid { document-id }?,
   attribute href { text }?,
   attribute uriid { xs:long }?,
   attribute frag { fragment-id },
   attribute title { text },
   attribute level { xs:integer }?,
   attribute type { string "none" | string "alternate" | string "embed" | string "transclude"},
   attribute display { "document" | "document+manual" | "document+fragment" | "manual"},
   attribute labels { text }?,
   attribute urititle { text }?,
   attribute mediatype { text }?,
   attribute documenttype { text }?,
   attribute reverselink { xs:boolean }?,
   attribute reversetitle { text }?,
   attribute reversetype { string "none"}?,
   attribute reversefrag { fragment-id }?,
   attribute unresolved { xs:boolean }?,
   attribute external { xs:boolean }?


This element was introduced in the first draft of PSML and is well supported from PageSeeder 5.1.

It replaces PSStandard's <blockXref> element.


In PSML, most attributes names and values are in lower case.


The types "replace" and "include" supported in PSStandard are no longer supported in PSML and should be replaced by "embed".

See also

Related element: <xref>

Created on , last edited on