---
title: "Element <blockxref>"
source: https://dev.pageseeder.com/psml/elements/element-blockxref.html
description: "PSML Element reference for <blockxref>"
last_updated: 2026-08-07T17:09:54+10:00
tokens: ~3014
---

# \<blockxref\>

## Summary

A [block level cross-reference](../../reference/glossary/block_xref.md).

This type of xref is usually used to insert content from another [document](../../reference/glossary/document.md) using the `embed` or `transclude` type. Or, it can be used to build table of contents.

> **Note:** The `@frag` attribute is required plus at least one of the following: - `@href` - `@docid` - `@uriid`

The content of this element, displayed as the link title, is generated. Although the original content is only INFORMATIONAL and is discarded by the upload process, there are two exceptions to this:

- If `@display="manual"` and `@title` is missing or empty, the content is used for the value of `@title`;  
OR
- If the xref cannot be resolved, some content helps users to understand or debug what went wrong with the xref.

> **Note:** For these reasons, it is always a good idea to include text in the element content.

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

When the [PSML](../../reference/glossary/psml.md) is processed, `<blockxref>` might contain the content of the targeted [document](../../reference/glossary/document.md) or [fragment](../../reference/glossary/fragment.md).

For inline level cross-references, use the [\<xref\> element](element-xref.md) instead.

> **Note:** Best practice recommends that information models limit PSML documents to no more than 1,000 inline `<xref>` and block `<blockxref>` elements in a single document.

## Usage context

| Element category | block content |
| --- | --- |
| PSML level | portable |
| Permitted content | text \* |
| Permitted parent | `<fragment>` `<xref-fragment>`... |
| HTML equivalent | `<a>` |
| OpenXML equivalent |  |

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

## Attributes

This element includes the following attributes:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| archived | `boolean` | no | Whether the target document is archived |
| config | `xref-config` | no | The configuration name for this xref |
| display | `xref-display` | no | Defines format of target link text |
| docid | `document-id` | maybe | The document ID of the target  |
| documenttype | `document-type` | no | The target document’s type |
| external | `boolean` | no | If `true` the target is a URL |
| frag | `fragment-id` | yes | The fragment ID of the target |
| href | `xs:string` | maybe | Path to the target document |
| id | `xs:long` | no | XLink ID of the cross-reference  |
| labels | `label-list` | no | A list of xref labels |
| level | `xref-level` | no | The level of heading the target document should start at |
| mediatype | `xs:string` | no | The target document media type |
| reverselink | `boolean` | no | A flag indicating if the link is bidirectional |
| reversetitle | `xs:string` | no | The title in the reverse direction |
| reversetype | `xref-type` | no | Always `none` |
| reversefrag | `fragment-id` | no | The fragment ID on the source |
| title | `xs:string` | no | The manually entered title |
| type | `xref-type` | no | Type for link processing (default is `embed`)  |
| unresolved | `boolean ` | no | If `true`, the target document could not be resolved |
| uriid | `xs:long` | maybe | URI ID of the target document |
| urititle | `xs:string` | no | Title of the target URI (generated) |
| urilabels | [label-list](../datatypes/pageseeder_datatypes.md) | no | Labels of the target URI (generated) |

### `@archived`

A boolean flag indicating whether the target document is archived. *INFORMATIONAL - ignored by upload.*

*This attribute was introduced in PSML v1.3 in PageSeeder 5.99.*

### `@display `

Defines how the target link text of this xref 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 [Xref display](../datatypes/pageseeder_datatypes.md).

### `@docid`

The [document ID](../../reference/glossary/document_id_docid.md) of the target. This value overrides the `@uriid` on upload.

### `@documenttype`

Refers to the xref target [documenttype](../../reference/glossary/document_type.md). *INFORMATIONAL - ignored by upload.*

### `@external`

If attribute value is `true`, the xref target is a URL. *INFORMATIONAL - ignored by upload.*

### `@frag`

Refers to the xref target fragment ID. When this value is `default`, it refers to the entire document. This value can also reference fragments other than PSML fragments.

### `@href`

When uploading, this might be a path relative to the current document or an absolute path that begins with a “`/`” character. If it is“ `#`”, the current document is the target. It must always be URL encoded unless `document/@level="processed"`.

This value overrides the `@docid` and `@uriid` on upload.

> **Note:** When `@href` is relative and in a [metadata format](../universal_format/Universal_Metadata_Format.md) URL being uploaded, it is relative to the upload folder. So the folder that URLs are uploaded to may affect xref resolution.

### `@id`

The ID of the XLink that corresponds to this cross-reference. *INFORMATIONAL - ignored by upload.*

### `@labels`

A comma-separated list of xref labels.

### `@level`

The level that the heading numbering of the target document starts from.

### `@mediatype`

Refers to the `mediatype` of the xref target document. *INFORMATIONAL - ignored by upload.*

> **Note:** The media type of PSML documents is `"application/vnd.pageseeder.psml+xml"`.

### `@reverselink`

A boolean attribute to indicate whether the xref is bidirectional or “reverse” link. When set to `true` (the default value), the xref also appears in the metadata of the target document.

### `@reversetitle`

A manually entered title to appear on the reverse link.

### `@reversetype`

Type for link processing of reverse link. As of version 5.97, there is only support for a value of `none`.

### `@reversefrag`

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

### `@title`

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.

### `@type`

The type defines how PageSeeder is to process the xref.

The following values are allowed:

- `none` – No link processing.
- `alternate` – An alternate representation 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.

> **Note:** The default type for `<blockxref>` is `embed`. For an inline `<xref>`, the default type is `none`.

### `@unresolved`

If `true`, the target document doesn’t exist. *INFORMATIONAL - ignored by upload.*

### `@uriid`

The URI ID of the target document.

Ignored by upload if on a different PS server.

### `@urititle`

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

### `@urilabels`

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.*

## Examples

When constructing `<blockxref>` elements, it is useful to remember that PageSeeder automatically expands a minimally-expressed link. All that is required is the address of the document and fragment and some content to make the link visible. PageSeeder sees all the following examples as valid:

```lang-xml
<blockxref href="filename.psml"
           frag="default">link title</blockxref>
```

```lang-xml
<blockxref docid="server-wide_uniqueid"
           frag="default">link title</blockxref>
```

```lang-xml
<blockxref uriid="9999" frag="5">link title</blockxref>
```

Also, documents containing these minimal links\* can be uploaded before the other end of the link is available.

After both ends of the xref are available, any user with the appropriate permission can go to the **Group maintenance** page under the **Admin** menu and select the option to **Resolve** references.

The PageSeeder server then resolves the `<blockxref>` element, adds the implied attributes and values and creates a `<reversexref>` element at the link destination.

*\* the third example is using a URIID, as this value is generated by the system, the target of this xref is already known.*

## Schema

### XML Schema

```lang-xml

<xs:element name="blockxref">

  <xs:complexType>
    <xs:simpleContent>
      <xs:attribute name="archived" type="xs:boolean"/>
      <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:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="document" />
            <xs:enumeration value="document+manual" />
            <xs:enumeration value="document+fragment" />
            <xs:enumeration value="manual" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>

      <xs:attribute name="type">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="none" />
            <xs:enumeration value="alternate" />
            <xs:enumeration value="embed" />
            <xs:enumeration value="transclude" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>

      <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:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="none" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>

      <xs:attribute name="reversefrag" type="fragment-id" /> 
      <xs:attribute name="unresolved" type="xs:boolean" />
      <xs:attribute name="external" type="xs:boolean" />

    </xs:simpleContent>
  </xs:complexType>
</xs:element>
```

### Relax Schema

```lang-relax

element blockxref {
   attribute archived { xs:boolean }?,
   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 }?
}
```

## Compatibility

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

> **Note:** In PSML, most attributes names and values are in lower case.