---
title: "How to create a shared glossary"
source: https://dev.pageseeder.com/get_started/tutorials/how_to_create_a_shared_glossary.html
last_updated: 2026-08-07T17:09:54+10:00
tokens: ~2987
---

# How to create a shared glossary

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

## Objective

This tutorial demonstrates how to create a pool of definitions for terms that can be shared between documents and exported to Word DOCX as customized glossary or definition lists.

## Prerequisites

To complete this tutorial requires:

- PageSeeder administrator access to a server with PageSeeder version 6.2003 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 **Shared glossary** or **Advanced auto-numbered publication**.
  2. Install the bundle under the root document type for your publication (e.g `references`, shown in the Document type field on the right of the dialog). **Click Install**.

#### Verify package content - project configuration files

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

> **Note:** If you chose the **Shared glossary** bundle any of the following marked as *Not required* might not appear.

##### 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. |
| `docx-citation-transform.xsl` | XSLT to convert PSML properties to DOCX citations, see [Export citations to DOCX: Post-processing](../../guide/publishing/ant_api/extensions/export_citations_to_docx.md). *Not required but is used for this tutorial.* |
| `psml-to-docx.xsl` | XSLT that generates a glossary in DOCX for the terms used in the publication. |

##### 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 | *Not required for this tutorial.* |
| `figure-caption` | block | *Not required for this tutorial.* |
| `table-caption` | block | *Not required for this tutorial.* |
| `asciimath` | inline | *Not required for this tutorial.* |
| `tex` | inline | *Not required for this tutorial.* |
| `pages` | inline | *Not required for this tutorial.* |
| `definition` | inline | Identifies words that should be linked to a definition. |

##### Document types

Select **Template configuration** from the left menu which should display these PSML document types:

| Document type | Description |
| --- | --- |
| `default` | The content of a publication. Includes a [schematron](../../reference/glossary/schematron.md) to check definitions and 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 and a schematron to list definition terms. |
| `asciimath` | *Not required for this tutorial.* |
| `bibliography` | *Not required for this tutorial.* |
| `definition` | Definitions of terms in publications. One term per document. |
| `endnotes` | *Not required for this tutorial.* |
| `footnotes` | *Not required for this tutorial.* |
| `help` | *Not required for this tutorial.* |
| `glossary` | A container for definitions used in a publication. When exported to DOCX, the definitions for any defined terms used in the publication will automatically be inserted here. |
| `source` | *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` | *Not required but is used for this tutorial.* |
| `pdf-export-config.xml` | *Not required for this tutorial.* |
| `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 **Word Export** column, scroll down and the following excerpt from the `word-export-config.xml` appears. This is the only specific export config required for the glossary (so that definition headings are the correct level in the TOC). The rest can be the default config.

```xml
  ...
  <elements label="definition">
    <heading>
      <level value="1" wordstyle="Heading Unnum 3" />
      <level value="2" wordstyle="Heading Unnum 4" />
    </heading>
  </elements>
  ...
```

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

### 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 dialogue. 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 on the right, 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 on the right, 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.

### Manage definitions

Linking terms to their definition in a glossary can be done using xrefs but if there are a large volume of definitions the xrefs might make the server and user interface slow. That's why this example uses 'weak linking' instead of xrefs, which means that a **definition** inline label is applied to a term which then matches with a corresponding **definition** document in the group that has the term as its title. There is no actual link between the two, but an implied link which we call 'weak linking'. It is much easier to add weak links and faster to process or display documents containing them.

1. In a content document, enter edit mode by double clicking on a paragraph.
2. Select a word in the paragraph you want to be a term.
3. Click on the Inline label (highlighter) icon at the top and select **Inline label definition**.
4. Press **Ctrl-S** to save.
5. Click the Document validation (tick) icon in the right margin and the following message should appear *“The definition for ‘\[your term\]’ does not exist”*.
6. Click the Group documents (folder) icon at the top and then on **Create document**.
7. Type your term as the Document title and select **Definition** as the Document type, then click **Create**. Creating this first definition document automatically creates a **definitions** folder, in the group **documents** folder.
8. Click **Open document** and double click the empty fragment under Synonym to edit it.
9. Enter a definition for your term.
10. Click next to **Synonym** and type another term which should match this definition (for example if your term was *subsystem* you could type *sub-system)*. Then press **Enter**.
11. Press **Ctrl-S** to save.
12. Go back to the original document. You can use the **RECENTLY VIEWED** list in the navigation drop down menu (top left).
13. Click on the Document validation (tick) icon in the right margin and the message *“No reports or errors”* should appear because your term has now been defined.
14. Go to your publication root document and add a document of type `glossary` to it. Press **Ctrl-S**, then click on the glossary document and enter edit mode by double-clicking in it.
15. This document contains a marker section titled *“Definitions - will be inserted here”*. When the publication is exported to Word the full definitions will be inserted here and the terms will be linked to them.
16. Mouse over the **(+)** just below *“Definitions - will be inserted here”* and click **insert fragment**. Enter a word used in the definition you previously created and apply the **definition** inline label to it here and in the original definition document. You’ll also need to create a definition document for this word so its definition will be included even though this term doesn't appear in the publication. This term actually appears in another definition, so we want to include it. Use this method to include any extra definitions you would like.
17. Go to your publication root document and click on the Document validation (tick) icon in the right margin.
18. Select **definition list** from the Available schemas drop down menu and click **Validate**.
19. For your information this will list all the terms currently used in the publication.

### Export as a Word document

1. Go to any document in your publication.
2. Click the Document export (rocket) icon in the left margin.
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 definitions have been inserted and each terms is linked to its definition.