---
title: "PSML document styles (CSS)"
source: https://dev.pageseeder.com/guide/configuration/psml/psml_document_style.html
description: "This document explains how to customize PSML document styling in PageSeeder using CSS, including the location of style sheets, mapping of PSML elements to HTML, CSS selectors, editor and dark mode considerations, and compatibility notes for different versions."
last_updated: 2026-09-14T13:54:30+10:00
tokens: ~1814
---

# PSML document styles (CSS)

The `document.css` is a CSS style sheet used to style [PSML](/reference/glossary/psml.md) documents in the user interface. It can be used to customize the display of content in PageSeeder.

## Location

Custom styles for PSML documents are located in your [project template](/reference/glossary/project_template.md):

`/WEB-INF/config/template/[project]/psml/[documenttype]/style`

The document CSS is loaded on top of the default document styles.

> **Note:** Since PageSeeder v6, you no longer need to import the default styles as they are always loaded.

## Styles

To format content, styles depend on the HTML markup generated from PSML. Generally the HTML is stable, but from time to time it evolves along with the PageSeeder server.

> **Warning:** Where `document.css` has been modified, always review the formatting after a PageSeeder upgrade. See the [compatibility](/guide/configuration/psml/psml_document_style.md) section in this article for details.

### Structure

PSML structural elements are mapped as follows:

| PSML | HTML Element | CSS Selector |
| --- | --- | --- |
| `<document>` | `<article>` | `.psml-document` |
| `<section>` | `<section>` | `.psml-section` |
| *Any fragment* | `<div>` | `.psml-fragment` |
| `<fragment>` | `<div>` | `.psml-fragment` |
| `<properties-fragment>` | `<div>` | `.psml-properties-fragment` |
| `<xref-fragment>` | `<div>` | `.psml-xref-fragment` |
| `<media-fragment>` | `<div>` | `.psml-media-fragment` |



### Identifiers

To format particular sections or fragments, use the following CSS selector to prefix your rules:

| PSML | HTML | CSS selector |
| --- | --- | --- |
| `<document type="abc">`  | `<article class="document-type-abc">`  | `.document-type-abc` |
| `<section id="X">` | `<section id="section-X">` | `#section-X` |
| `<fragment id="Y">` | `<div id="fragment-Y">` | `#fragment-Y` |

These selectors no longer work for transcluded content.

The document type CSS selector is necessary if you need to use different styles based on the [document type](/psml/elements/element_document.md).

> **Note:** Don’t apply rules directly to these CSS selectors as these elements include content necessary for the user interface (such as buttons and menus) that shouldn’t be styled.

### Content

Because PSML content appears under the `psml-content` class, prefix CSS selectors with `.psml-content`. 

| PSML | HTML Element | CSS Selector\* |
| --- | --- | --- |
| `<para>` | `<p>` | `p` |
| `<heading level="1">` | `<h1>` | `h1` |
| `<heading level="2">` | `<h2>` | `h2` |
| `<heading level="3">` | `<h3>` | `h3` |
| `<heading level="4">` | `<h4>` | `h4` |
| `<heading level="5">` | `<h5>` | `h5` |
| `<heading level="6">` | `<h6>` | `h6` |
| `<list>` | `<ul>` | `ul` |
| `<nlist>` | `<ol>` | `ol` |
| `<item>` | `<li>` | `li` |
| `<preformat>` | `<div class="psml-preformat">` | `.psml-preformat` |
| `<block>`  | `<div class="psml-block">` | `.psml-block`  |
| `<inline>` | `<span class="psml-inline">` | `.psml-inline`  |
| `<image>`  | `<figure class="psml-image">`  | `.psml-image` |
| `<xref>`  | `<span class="psml-xref">` | `.psml-xref`  |
| `label="abc"`  | `class="label-abc"`  | `.label-abc` |
| `numbered="true"` | `data-numbered="true"` | `[data-numbered]` |
| `prefix="1.2.3"` | `data-prefix="1.2.3"` |  |
| `role="xyz"` | `data-role="xyz"` | `[data-role=xyz]` |
| `<para label="1">`  | `class="indent-1"`  `data-indent="1"`  | `.indent-` |

> **Note:** Where the same label has been used on different PSML element (block, inline, image or xref), differentiate them with the CSS element selector.

> **Note:** \* remember to include `.psml-content` with these selectors. 

### Styles in editor

By default, the same styles are applied when viewing and editing. To format the content one way for viewing and a different way for editing, use the `editor-on` class.

For styles to appear in the editor only, use:

- `.psml-document.editing-on`
- or `.psml-document.document-type-[type].editing-on` if the styles only apply to that document type.

For styles to appear in the document view only, use:

- `.psml-document:not(.editing-on)`
- or `.psml-document.document-type-[type]:not(.editing-on)` if the styles only apply to that document type.

> **Note:** In edit mode, the HTML is slightly different as it doesn’t include markup used to provide additional functionality in view mode. - Images are represented as element `<img>` and don’t include the `psml-image` wrapper. - Xrefs, transclusions, and links are represented as element `<a>` and don’t include the `psml-xref`, `psml-transclusion`, or `psml-link` wrapper. - Preformatted blocks are represented as `<pre>` and don’t include the `psml-preformat` wrapper or any markup used for syntax highlighting. - Math inline label are text only and don’t include the formatted expression.

### Styles in dark mode

Consider dark mode when customising styles, especially if you change the color background.

To set styles specific to dark mode, wrap your rules in a **`prefers-color-scheme`** CSS media feature block.

```css
@media (prefers-color-scheme: dark) {

  /* Dark mode specific rules go here */

}
```

## Examples

There are several examples in the [CSS sample code](/reference/sample_code/css.md).

## Compatibility

### Before version 6

The version 5 user interface was using the following mapping.

| PSML | HTML Element | CSS Selector | Compatibility |
| --- | --- | --- | --- |
| `<document>` | `<article>` | `.psml-document` | ok |
| `<section>` | `<section>` | `.psml-document section` | warning |
| *Any fragment* | `<div>` | `.fragment` | warning |
| `<fragment>` | `<div>` | `.psml-fragment` | warning |
| `<properties-fragment>` | `<div>` | `.psml-properties-fragment` | warning |
| `<xref-fragment>` | `<div>` | `.psml-xref-fragment` | warning |
| `<media-fragment>` | `<div>` | `.psml-media-fragment` | warning |
| `<section id="X">` | `<section id="section-X">` | `#section-X` | ok |
| `<fragment id="Y">` | `<div id="fragment-Y">` | `#fragment-Y` | ok |
| `<para>` | `<p>` | `p` | ok |
| `<heading level="1">` | `<h1>` | `h1` | ok |
| `<heading level="2">` | `<h2>` | `h2` | ok |
| `<heading level="3">` | `<h3>` | `h3` | ok |
| `<heading level="4">` | `<h4>` | `h4` | ok |
| `<heading level="5">` | `<h5>` | `h5` | ok |
| `<heading level="6">` | `<h6>` | `h6` | ok |
| `<list>` | `<ul>` | `ul` | ok |
| `<nlist>` | `<ol>` | `ol` | ok |
| `<item>` | `<li>` | `li` | ok |
| `<preformat>` | `<pre>` | `pre` | ok |
| `<block label="A">` | `<div class="label-a">` | `.label-a` | ok |
| `<inline label="B">` | `<span class="label-b">` | `.label-b` | ok |

The warning icons indicate that you need to update your CSS, because it has changed in version 6.

### Before ver 5.8

> **Deprecated:** Previous versions of PageSeeder use the following rules in the document view:

| PSML | HTML Element | CSS Selector |
| --- | --- | --- |
| `<document>` | `<article>` | `article` |
| `<section>` | `<section>` | `section` |
| `Any fragment` | `<div>` | `.ps-editcontent` |
| `<properties-fragment>` | `<div>` | `.psml-properties` |
| `<xref-fragment>` | `<div>` | `.psml-xrefs` |

Where custom CSS has been used with previous versions of PageSeeder, review carefully after upgrading.