Post Editor API

The Publii's post editor is based on the TinyMCE editor and allows you to add some modifications based on the used theme or configuration overrides.

Custom post editor CSS styles

To provide the best experience for the theme users, theme developers can want to add custom CSS styling to the post editor. If you want to add custom CSS just create a

assets/css/editor.css file in your theme. That file will be loaded after the default post editor CSS file - so you will be able to override any default CSS rules of the post editor.

Changing post editor default configuration

We always trying to create best solutions for most of the Publii users, but we understand that post editor is a complex tools and user needs can be very different. That's why we have allowed users to override default TinyMCE configuration by custom configuration file or custom JS scripts.

Custom Formats

Theme developers can add custom formats which allows them to create custom HTML structures which can be easily injected into the post editor. These formats are available under "Formats" dropdown list in the post editor UI and also in the inline toolbar of the post editor under "Select style" dropdown list.

To add custom formats to your theme, just create under theme's config.json file field called "customElements".

Example customElements field which creates four custom formats - "Info", "Highlight", "Success" and "Drop cap":

"customElements": [
    {
        "label": "Info",
        "cssClasses": "msg msg--info",
        "selector": "p"
    },
    {
        "label": "Highlight",
        "cssClasses": "msg msg--highlight ",
        "selector": "p"
    },
    {
        "label": "Success",
        "cssClasses": "msg msg--success",
        "selector": "p"
    },
    {
        "label": "Drop cap",
        "cssClasses": "dropcap",
        "selector": "p"
    }
]

As you can see - every custom format element is represented by object which contains three fields:

label - it is a format name displayed under dropdown lists in the post editor,
cssClasses - it is a list of CSS classes used in the injected element - you can style them in the custom editor.css file described above,
selector - it is a tag name used to wrap the content of the custom format.

It is also possible to limit the visibility of the custom formats to specific editors.

Publii uses TinyMCE editor in two places - in the post editor and under theme settings. Using two additional fields for the custom formats definitions:

postEditor - if true, will allow the custom format to be displayed under post editor,
themeSettings - if true, will allow the custom format to be displayed under theme settings WYSIWYG editors.

You can specify where they will be displayed:

"customElements": [
    {
        "label": "Info", 
        "cssClasses": "msg msg--info",
        "selector": "p",
        "postEditor": true, // will display under post editor
        "themeSettings": false // won't display under theme settings
    },
    {
        "label": "Highlight",
        "cssClasses": "msg msg--highlight ",
        "selector": "p",
        "postEditor": false, // won't display under post editor
        "themeSettings": true // will display under theme settings
    },
    {
        "label": "Success",
        "cssClasses": "msg msg--success",
        "selector": "p",
        "postEditor": false // won't display under post editor and theme settings
    },
    {
        "label": "Drop cap",
        "cssClasses": "dropcap",
        "selector": "p",
        "themeSettings": true // will display under post editor and theme settings as postEditor when not exists is treated as true
    }
]

The default value for the postEditor field is true. For the themeSettings field, the default value is false. It means that custom formats without these values defined, will be displayed only under the post editor.