---
title: "How to auto-number a publication"
source: https://dev.pageseeder.com/get_started/tutorials/how_to_auto-number_a_publication.html
last_updated: 2026-08-11T16:08:26+10:00
tokens: ~3210
---

# How to auto-number a publication

| Property | Value |
| --- | --- |
| Skills required | XML |
| Time required (minutes) | 15 |
| Intended audience | Developer |
| Difficulty | Easy |
| Category | Document |

## Objective

This tutorial demonstrates the auto-numbering for headings, paragraphs, appendices, and objects such as tables and images, and the ability to reference those numbers, for example, “see paragraph x.x”, confident that the referential integrity will correctly export to Word.

## Prerequisites

To complete this tutorial requires:

- PageSeeder administrator access to a server with PageSeeder version 6.2 or later installed.

All the files for this tutorial are on [Github](https://github.com/pageseeder/pageseeder-tutorials/tree/master/configuring_publications).

## Tutorial

### Project setup and installing configuration bundle

1. Login to PageSeeder as an administrator.
2. Go to the project where you would like to install these capabilities. Alternatively create a new project by clicking the tools **System administration **button at top right. Then click on **New project** under **Projects & Groups** and enter a project name, plus any description, then **Submit**.
3. Click the wrench **Project administration** button at the top.
4. Select **Template files** from the left menu and click the magic **Create** button at the bottom of the page to open the **Samples dialog**.
5. **Install a configuration bundle** – Click the filestack **Bundle** button, then in the **Bundle type** field, select **Document type** from the dropdown.


  1. Click the **Select** button to the right of a bundle – for this example, select **Basic auto-numbered publication**.* You can also select **Intermediate** or **Advanced** if you want bibliography or glossary features.*
  2. Install the bundle under the root document type for your publication (e.g. `references`, shown in the Document type field on the left of the dialog). **Click Install**.

#### Verify package content - project configuration files

In the **Template files** page check the files as follows.

##### Export process

The `psml/references/export` folder (or the document type you specified) contains the following files:

| Filename | Description |
| --- | --- |
| `build.xml` | Custom ANT script for exporting to DOCX. |
| `psml-to-docx.xsl` | XSLT that adds the inline labels necessary for figure / table captions to auto-number in DOCX. |

##### Labels

The `label` folder contains the following file:

| Filename | Description |
| --- | --- |
| `label-config.xml` | The `label-config.xml`, contains all the available labels for a project. |

You can select **Labels** from the left menu and the following should be displayed:

| Label | Type | Description |
| --- | --- | --- |
| `appendix` | document | Identify appendix for alternate numbering. |
| `figure-caption` | block | To identify text for a figure or image caption. |
| `table-caption` | block | To identify text for a table caption. |
| `asciimath` | inline | *Not required for this tutorial.* |
| `tex` | inline | *Not required for this tutorial.* |

##### Publication types

Select **Template configuration** from the left menu, then **Publication types** tab. In the first column, it should show the **report** publication type, which includes these files:

| Filename | Description |
| --- | --- |
| `publication-config.xml` | The configuration file that determines numbering in PageSeeder, including heading, paragraph, and figure / table numbering. |
| `pdf-export-config.xml` | The configuration file that determines the formatting of PSML as PDF, see [Exporting to PDF](/guide/documents/pageseeder_fo_config.md). |
| `word-export-config.xml` | The configuration file that determines the formatting of PSML as DOCX, see [Export Microsoft Word DOCX config usage](/guide/publishing/ant_api/extensions/microsoft_word_docx_export_config_usage.md). |
| `word-export-template.docx` | The default DOCX template which you can customize. |

Click **edit** next to **report **in the **Config** column and the following `publication-config.xml` appears. It can be customized for your own numbering schemes, see [Publications and publication types](/guide/configuration/publication_types.md). After saving changes, click the **reload** button in the last column to apply them.

```xml
<publication-config>
  <toc title-collapse="always"
       block-labels="table-caption,figure-caption"/>
  <levels xref-relative-to="heading"
          para-relative-to="6" />
  <numbering skipped-levels="strip">
    <schemes>
      <scheme level="1" type="decimal"    format="[1]" />
      <scheme level="2" type="decimal"    format="[1.][2]" />
      <scheme level="3" type="decimal"    format="[1.][2.][3]" />
      <scheme level="4" type="decimal"    format="[1.][2.][3.][4]" />
      <scheme level="5" type="decimal"    format="[1.][2.][3.][4.][5]" />
      <scheme level="6" type="decimal"    format="[1.][2.][3.][4.][5.][6]" />
      <scheme level="7" type="loweralpha" format="[(7)]" element="para" />
      <scheme level="7" type="decimal"    format="[Table 1-][7]"
                        block-label="table-caption" element="para"/>
      <scheme level="7" type="upperalpha" format="[Fig 1-][7]"
                        block-label="figure-caption" element="para"/>
      <scheme level="8" type="lowerroman" format="[(8)]" element="para" />
      <scheme level="9" type="upperroman" format="[(9)]" element="para" />
      <scheme level="10" type="upperalpha" format="[(10)]" element="para" />
    </schemes>
  </numbering>
  <numbering skipped-levels="strip" document-label="appendix">
    <schemes>
      <scheme level="1" type="upperalpha" format="[Appendix 1]" />
      <scheme level="2" type="decimal"    format="[1-][2]" />
      <scheme level="3" type="decimal"    format="[1-][2.][3]" />
      <scheme level="4" type="decimal"    format="[1.][2.][3.][4]" />
      <scheme level="5" type="decimal"    format="[1.][2.][3.][4.][5]" />
      <scheme level="6" type="decimal"    format="[1.][2.][3.][4.][5.][6]" />
      <scheme level="7" type="loweralpha" format="[(7)]" element="para" />
      <scheme level="8" type="lowerroman" format="[(8)]" element="para" />
      <scheme level="9" type="upperroman" format="[(9)]" element="para" />
      <scheme level="10" type="upperalpha" format="[(10)]" element="para" />
    </schemes>
  </numbering>
</publication-config>

```

> **Tip:** If you prefer a different name to **report**, select **Template files** from the left menu, scroll down to the **report** folder and select **Rename** from the right drop-down menu. Change the name and click **Rename**. Remember to substitute the new name whenever this tutorial mentions **report**.

##### Document types

The **Template configuration** page should display these PSML document types:

| Document type | Description |
| --- | --- |
| `default` | The content of a publication. Includes a CSS style to display footnote and endnote references as superscripts in the user interface. |
| `references` (or your type) | The root document of a publication. Includes the custom export configuration. |
| `endnotes` | *Not required for this tutorial.* |
| `footnotes` | *Not required for this tutorial.* |
| `help` | *Not required for this tutorial.* |

##### XRef configuration

Select **Edit XRef configs** (top right).

| Filename | Description |
| --- | --- |
| `xref-config.xml` | The [Xref configuration](/guide/configuration/psml/psml_xref_config.md) for the import of cross-references including footnotes, endnotes, citations, and more as listed below. |

The following xref configs should be listed (see [Xref config](/guide/configuration/psml/psml_xref_config.md)):

- **footnote** – to insert a footnote reference.
- **endnote** – to insert an endnote reference.
- **para** – to create an xref to a para with the number of the paragraph as the title. For example, “*see clause 14.2.a*” where the xref will automatically adjust if the paragraph number changes.
- **internal-para** – when an xref source and destination are both under the same parent number and can therefore use “relative references”. For example, “*see (a)*” instead of “*see clause 14.2.a*”.
- **numbered-heading** – to reference to a numbered heading. For example, “*see section 14 Privacy*” where the xref will automatically adjust if the heading number or text changes.
- **caption** – to create an xref to a numbered image or table caption.

> **Note:** The correct xref config must be selected when creating an xref in your publication so that they are numbered correctly when exported to DOCX.

### Creating a publication

> **Note:** As an alternative to this step use a preprepared example publication as follows: 1. In PageSeeder go to the project from Step 1 and create a new group by clicking the wrench **Project administration** button at the top. Then select **Create group** from the left menu and enter a group name, plus any description, then **Submit** and **Go to group**. 2. Click **Group documents** (folder icon) at the top, then click the **documents** folder. 3. Select **Upload document** from the (+) menu top right and drag the `documents-[date].zip` file (downloaded from Github - see link under **Prerequisites**) to the upload dialogue. 4. Click the **Unzip** icon next to this zip file. 5. Click the **Continue** button at the bottom of the dialog. 6. Click the **Confirm and upload** button and wait for the “Successfully uploaded” message, then click **Close**. 7. Click the “System Report” folder, then click the “System Report” document. 8. Click the **Document information** icon in the right sidebar, click **Make this document a publication**, ensure there is a Publication ID and for this example, select Publication type "`report`". Click **Submit** then **Save** and refresh the page in your browser.

Create a publication root document and content as follows:

1. In PageSeeder, go to a group under the project from Step 1. Alternatively, create a new group by clicking the wrench **Project administration** button at the top. Then select **Create group** from the left menu and enter a group name, plus any description, then **Submit **and **Go to group**.
2. In this group, create or open an existing document of the root type you selected previously (e.g. `references` ).
3. Click the **Document information** icon in the right sidebar, click **Make this document a publication**, ensure there is a Publication ID and for this example, select Publication type "`report`". Click **Submit** then **Save**.
4. If there is no existing content, double-click in the root document, click **Browse** and create a document (for example `default` type), select it and save. On the root document press **Ctrl-S** to save everything.
5. Click a content document, add some headings and paragraphs if required and test the auto-numbering by making them numbered with the autonumber **Toggle auto-number** icon in the edit toolbar. Press **Ctrl-S** to generate numbers.
6. Place the cursor in the text and select the xref **Insert/edit cross-reference** icon in the document toolbar. Under Configuration select **Paragraph**, **Internal paragraph** or **Numbered heading**. Click on a document and then on the target numbered paragraph or heading and **Save**. Press **Ctrl-S** to generate the xref numbering.
7. Make the top level heading in the content document numbered and press **Ctrl-S**. Click the **Document information** icon in the right sidebar, click **appendix** next to **Document labels**, then click the **Save** button.
8. Refresh the page in your browser and **“Appendix A”** will appear before the first heading, with **"A-"** prefixing the numbering on other headings. Remove the appendix label, save, refresh and the numbering will revert.

### Export as a Word document

1. Go to any document in your publication.
2. Click the Document export (rocket) icon in the right sidebar.
3. Under the **Choose an export action** drop down, select **Export publication as custom DOCX** and click **Run**.
4. Open the document in Microsoft Word and see how the auto-numbering for headings, paragraphs, appendices, tables, images, and the references to these are displayed by Word.

### Export as a PDF document

1. Go to the root document in your publication.
2. Click the **Document information** icon in the right sidebar, click plus next to **Document labels, **type **publication**, then click the **Save** button. *This is to create a cover page.*
3. Click the Document export (rocket) icon in the left sidebar.
4. Under the **Choose an export action** drop-down, select **Export publication as PDF** and click **Run**.
5. Open the PDF and see how the auto-numbering for headings, paragraphs, appendices, tables, images, and the references to these are displayed in PDF.