--- title: "How to import and export LwDITA in PageSeeder" source: https://dev.pageseeder.com/get_started/tutorials/how_to_import_and_export_lwdita_in_pageseeder.html last_updated: 2026-08-11T16:31:24+10:00 tokens: ~3761 --- # How to import and export LwDITA in PageSeeder | Property | Value | | --- | --- | | Skills required | XML | | Time required (minutes) | 45 | | Intended audience | Developer | | Difficulty | Medium | | Category | Document | ## Objective PageSeeder can be used to edit, manage and publish content from different XML formats. This tutorial shows how to import/export and edit Lightweight [DITA](https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture) (LwDITA) XML format in PageSeeder. It includes how to: - model the LwDITA format in PSML; - import LwDITA as PSML using `map` and `topic` document types; - create and edit `map` and `topic` documents in PageSeeder; - export `map` documents as DOCX, PDF and back to LwDITA format. ## Prerequisites To complete this tutorial requires: - Administrator access to a PageSeeder server. All the necessary files for this tutorial are on [Github](https://github.com/pageseeder/pageseeder-tutorials/tree/master/import_export_lwdita). ## Tutorial ### Model LwDITA in PSML The following resources were used to map the LwDITA XDITA format elements and attributes to PSML elements and attributes. - [http://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.pdf](http://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.pdf) - [http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html](http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html) for background explanations. - [https://github.com/oasis-tcs/dita-lwdita](https://github.com/oasis-tcs/dita-lwdita) for DTDs and sample XML. - [PSML elements](/psml/elements.md) For simplicity a one to one file mapping between LwDITA XDITA files and PSML files was used and the mapping below was created. Any customization of PageSeeder document configurations has also been listed in the **Document config** column. #### Mapping of general XDITA elements to PSML | Component | XDITA | PSML | Document config | | --- | --- | --- | --- | | Alternate text | `` | `@alt` on `` | | | Body | `` | `
` | | | Bold | `` | `` | | | Cross reference | `` | `` for external target; `` for internal target | | | Data | `` | `` under `` | `topic/document-template.psml` can be used to configure `property/@name` values | | Definition description | `
` | `` content | | | Definition list entry | `` | `` | | | Definition term | `
` | `@prefix` on `` | | | Definition list | `
` | `` | `` in `topic/document-config.psml` | | Description | `` | `` in `` | `` in `topic/document-config.psml` | | Figure | `` | `` | `` in `topic/document-config.psml` | | Footnote | `` | `` | `` in `topic/document-config.psml` | | Image | `` | `` | | | Italics | `` | `` | | | Key definition | `` | `[@keys][linktext]` | `` in `map/document-config.psml` | | Link text | `` | See `keydef` above | | | List item | `
  • ` | `` | | | Map | `` | `` | `` in `map/document-config.psml` | | Note | `` | `` | `` in `topic/document-config.psml` | | Ordered list | `
      ` | `` | | | Paragraph | `

      ` | `` | | | Navigation title | `` | `@title` on `` or `` | | | Phrase | `` | if `@keyref` then `[@keyref];` else if `@props` then `` | `` in `topic/document-config.psml` | | Preformatted text | `

      ` | `` |  |
| Prolog | `` | `` |  |
| Section | `
      ` | `
      ` or `` |  |
| Short description | `` | `` under `` |  |
| Table | `` | `` |  |
| Simple table entry | `` | ` ` |  |
| Simple table header | `` | `` |  |
| Simple table row | `` | `` |  |
| Subscript | `` | `` |  |
| Superscript | `` | `` |  |
| Title | `` | `<block label="title">` in `<block label="fig">; <heading level="2">` in `<fragment>` |  |
| Topic | `<topic>` | `<document type="topic">` | `<creation>` in `topic/document-config.psml` |
| Topic metadata | `<topicmeta>` | Not applicable |  |
| Topic reference | `<topicref>` | `<blockxref>` |  |
| Underline | `<u>` | `<underline>` |  |
| Unordered list | `<ul>` | `<list>` |  |

#### Mapping of multimedia XDITA elements to PSML

| Component | XDITA | PSML |
| --- | --- | --- |
| Audio | `<audio>` | `<properties-fragment type="audio">` |
| Autoplay | `<media-autoplay>` | `<property name="media-autoplay">` |
| Controls | `<media-controls>` | `<property name="media-controls">` |
| Loop | `<media-loop>` | `<property name="media-loop">` |
| Muted | `<media-muted>` | `<property name="media-muted">` |
| Poster | `<video-poster>` | `<property name="video-poster">` |
| Source | `<media-source>` | `<property name="media-source" count="n">` |
| Track | `<media-track>` | `<property name="media-track" count="n">` |
| Video | `<video>` | `<properties-fragment type="video">` |

These are all configured in `topic/document-template.psml` and `topic/editor-config.json`.

#### Mapping of XDITA attributes to PSML

Following is a detailed breakdown of mapping between the languages.

##### Architecture attributes

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| ditaarch | `@xmlns:ditaarch` | Not applicable |  |
| DITAArchVersion | `@ditaarch:DITAArchVersion` | Not applicable |  |
| Domains | `@domains` | Not applicable |  |

##### Localization attributes

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Direction | `@dir` | Not applicable |  |
| Language | `@xml:lang` | Not applicable |  |
| Translate | `@translate` | Not applicable |  |

##### Data definition

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Name | `@name` | `@name` on `<property>` | `topic/document-template.psml` can be used to configure `@name` values |
| Value | `@value` | `@value` on `<property>` |  |

##### Figure display attributes

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Expanse | `@expanse` | `<inline label="expanse">` | `<labeling>` in `topic/document-config.psml` |
| Frame | `@frame` | `<inline label="frame">` | `<labeling>` in `topic/document-config.psml` |
| Scale | `@scale` | `<inline label="scale">` | `<labeling>` in `topic/document-config.psml` |

##### Filtering attribute

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Props | `@props` | `<inline label="props">` | `<labeling>` in `topic/document-config.psml` |

##### Footnote control

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Callout | `@callout` | Not implemented but could use `<inline label="callout">` |  |

##### Image size

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Height | `@height` | `@height` |  |
| Width | `@width` | `@width` |  |

##### Note type

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Type | `@type` | `@label` on `<inline>` |  |

##### Processing attribute

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Output class | `@outputclass` | Not implemented but could use `@role` on some elements |  |

##### Reference attributes

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Link target | `@href` | `@href` and `@frag` |  |
| Format of target resource | `@format` | `@mediatype` |  |
| Relationship of source to target | `@scope` | Not implemented but could use `@labels` |  |

##### Reuse attributes

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Identifier | `@id` | `@id` on parent `<fragment>` |  |
| Content reference | `@conref` | `@href` on `<blockxref type="transclude">` |  |

##### Video size

| Component/Set | XDITA | PSML | Document config |
| --- | --- | --- | --- |
| Height | `@height` | `<property name="height">` | `topic/document-template.psml` and `topic/editor-config.json`. |
| Width | `@width` | `<property name="width">` | `topic/document-template.psml` and `topic/editor-config.json`. |

#### `@conref` support

This tutorial has been implemented with support for  `@conref` for \<`audio>`, `<dl>`, `<dentry>`, `<note>`, `<ol>`, `<p>`, `<pre>`, `<section>`, `<simpletable>`, `<ul>`, `<video>`

To use `@conref` with the following objects, the content must be wrapped with a `<p>` element: `<fn>`, `<dt>`, `<dd>`, `<li>`, `<sentry>`, `<sthead>`, `<strow>`

 

### Configure LwDITA project customizations

1. Login to PageSeeder as an administrator.
2. Click on **New project** and enter the project name "lwdita", any description and any owner, then click **Submit**.
3. Click **Home page** then **New group** and enter the group name "tutorial", any description, then click **Submit**.
4. Select **Developer** perspective from the cube icon (top left).
5. Select **Project files** from the **Dev** menu.
6. Drag the `ps-lwdita-[date].zip` file (downloaded from Github) to the drop files area.
7. Click the **Import** icon next to this zip file.
8. Select **Toolbox** from the **Dev** menu, then click on **Project files** under **PageSeeder publisher** on the right.
9. Drag the `pspublisher-lwdita-[date].zip` file (downloaded from Github) to the drop files area.
10. Click the **Import** icon next to this zip file.
11. Click on **Publish scripts** and then click **edit** to the right of the "upload dita" row (see below).
12. This is the ANT script used to import a .dita file as PSML. Click on the **Help** (?) icon (top right) to find out more information.
13. Click on **Go to folder** and then on **lwdita-to-psml.xsl**.
14. This is the XSLT used to convert a .dita file to a PSML file. It implements all the mapping rules described above and is executed by the ANT script.
15. Go back to the first **Project files** page (it should be in another tab) and click on **Home**.

![](/content/images/tutorials/lwdita-publish-scripts.webp) 

### Import LwDITA as PSML

1. Ensure you are on the home page for the “lwdita-tutorial” group then click on the **upload document** icon (see below).  

![](/content/images/tutorials/lwdita-tutorial-home.webp)
2. Drag the `sample-lwdita.zip` file (downloaded from Github) to the drop files area.
3. Click the **Unzip** icon next to this zip file.
4. Click the **List media** button (bottom right).
5. Click **Options** next to DITA or DITAMAP and click on **Import LwDITA as PSML**.
6. Click the **Continue** button at the bottom.
7. Wait a little while until the Confirm upload dialog appears, then click **Continue** and wait for the message "Successfully uploaded".
8. Under this message click on the **remotelighting.psml** link. This is the main ditamap file converted to PSML and should look as shown below.  

![](/content/images/tutorials/lwdita-map.webp)
9. Click on the links to explore the topic documents.
10. Click on the **Remote Control Specifications** topic, then on the document **settings** icon and select **outline transclusions** (see below). This shows how the DITA conref appears as a transclusion at the bottom.  

![](/content/images/tutorials/lwdita-transclusion.webp)

### Create and edit `map` and `topic` documents

1. On the `map` document click the **pencil** next to the Topicrefs section.
2. Click **Create Document**.
3. Select **LwDITA topic** and type a title "My topic".
4. Click **More document options** then 


  1. type a Document ID “lwdita-tutorial\_mytopic” (for this tutorial we use the format \[full group name\]\_\[topic ID\]) - note the underscore before topic ID.
  2. type a Description “This is my topic.”
5. Click **Submit** then click **Save**.
6. Click on the **My topic** link and then click the add fragment icon (on the right). 


  1. Type “This is my content.”
  2. Press enter and type “This is my note.”, then select the text, right click and select **Add block 'note'**.
  3. Click **Save**.
7. Mouse over the pencil icon (on the right) and then the add fragment icon and choose **Video**. 


  1. Next to **Autoplay:** select “true”.
  2. Next to **Source:** type a URL to a video (e.g. https://www.youtube.com/watch?v=...) and click **Add**.
  3. Click **Save**.
8. Select **Document config** from the **Dev** menu.
9. To see how creation and editing are configured click on **edit** under “Document template”, “Document config” and “Editor config”, next to the “map” and “topic” document types (see below). When viewing files click on the **Help** (?) icon (top right) to find out more information.

![](/content/images/tutorials/lwdita-document-config.webp) 

### Export `map` documents as DOCX, PDF and LwDITA

1. On the `map` document click the **export** icon (top left).  
![](/content/images/tutorials/lwdita-export.webp)
2. 
Click on **Create DocX for LwDITA** and click **Export**. Open the document in Word and notice that the `keyrefs` have been replaced by the `keydef` text "Remote Lighting Network" and the video/audio by links. This is done by the `lwdita-post-transform.xsl` described below. The "My topic" content should be at the bottom.

3. 
Click on **Create PDF for LwDITA** and click **Export**. It should have the same replacements as for the DOCX.

4. 
Click on **Export as LwDITA** and click **Export**. Extract the `.zip` file and open the `.ditamap` and `.dita` files with a text editor (e.g. Notepad) to check the content. Note the new `my_topic.dita` file that was not in the original `sample-lwdita.zip` file.

5. 
Select **Document config** from the **Dev** menu and then click on **Publish scripts** (top right).

6. Click **edit** to the right of the "(Create DocX for LwDITA)" row (see below).
7. This is the ANT script used to export as DOCX. Click on the **Help** (?) icon (top right) to find out more information.
8. Click on **Go to folder** and then on **lwdita-post-transform.xsl**.
9. This is the XSLT used to replace the `keyrefs` by the `keydef` text and the video/audio by links. It is executed by the `<ps:process>` ANT task.
10. Click on **Publish scripts** and then on **edit** to the right of the "(Create PDF for LwDITA)" row (see below). This is the ANT script used to export as PDF.
11. Click on **Publish scripts** and then on **edit** to the right of the "(Export as LwDITA)" row (see below). This is the ANT script used to export as LwDITA.
12. Click on **Go to folder** and then on **psml-to-lwdita.xsl**.
13. This is the XSLT used to convert a PSML file to an LwDITA file. It implements the reverse of all the mapping rules described above and is executed by the ANT script.

![](/content/images/tutorials/lwdita-export-scripts.webp)