Package metadata
The package metadata is a set of CKEditor 5-related data describing plugins that the package delivers. It allows for the automated detection of plugins and building them by an external builder.
In the case of official CKEditor 5 packages (as well as some partner ones), this data is used by the CKEditor 5 Builder and allows for building the Features’ HTML output page presenting a list of all official CKEditor 5 plugins.
The package metadata should be saved in the special ckeditor5-metadata.json
file in the root of the package published on npm.
Only plugins that provide major functionalities should be described in the metadata file. For example, the metadata file for the @ckeditor/ckeditor5-mention
package describes only the Mention
plugin, which is a “glue plugin” that loads both the editing and UI parts of the mention feature. This package does not expose the MentionEditing
and MentionUI
plugins that cannot be used alone.
# Data format for plugin metadata
The ckeditor5-metadata.json
file is a JSON object that holds the plugins
array. Each element of this array should be an object containing information about a different plugin delivered by the package. Below is a list of all metadata properties that can be used to describe a plugin:
name
– A human-readable name of the plugin.description
– A human-readable short description of the plugin.docs
– An absolute or relative URL to the plugin documentation. If this URL is relative, it leads to the CKEditor 5 documentation in https://ckeditor.com/docs/ckeditor5/latest/.path
– A path to the file, relative to the metadata file that exports the plugin.className
– The name of the class used to create the plugin. This class should be exported from the file using theexport default
syntax.requires
– An array of the plugin’s soft requirements and other non-explicit requirements. It should contain class names of plugins that should be included if this plugin is added. If the element of this array is another (nested) array containing plugins’ class names, it means that at least one plugin listed from this nested array is required, but not all of them.registeredToolbars
– An array of all toolbar names registered by the plugin. These names need to represent the configuration path (for example,table.contentToolbar
foreditorConfig.table.contentToolbar
andtable.tableToolbar
for theeditorConfig.table.tableToolbar
, which are registered by theTable
plugin).uiComponents
– An array of objects that describes UI components exported by the plugin. Each object in this array may contain:name
– The name of the component the plugin exports. It should match the actual UI name registered by the plugin.type
– The component type:Button
,SplitButton
orDropdown
.iconPath
– The path to the SVG icon forButton
orSplitButton
. The path can be either relative to the package or absolute – linking to a resource from another package.label
– Text content forDropdown
components.toolbars
– An array of toolbar names that a given UI component can be added to. Some UI components may be added to multiple toolbars.
htmlOutput
– An array of objects that defines all possible HTML elements which can be created by a given plugin. The main property in this object iselements
. Other properties (likeclasses
,styles
,attributes
) only apply to items defined in theelements
property within a given object. The wildcard character*
is used to mark any value. The full list of all these properties includes:elements
– HTML elements (a single one or an array of these) that are created or altered by the plugin. The pseudo-element$block
indicates that a given plugin applies classes, styles or attributes (defined in appropriate properties) for all block elements.classes
– CSS class names (a single one or an array of these) that may be applied to the HTML elements defined in theelements
property.styles
– Inline CSS styles (a single one or an array of these) that may be applied to the HTML elements defined in theelements
property.attributes
– HTML attributes (a single one or an array of these) other thanclass
andstyles
(covered separately) that might be applied to the HTML elements defined in theelements
property.implements
– The name of an element or a pseudo-element which indicates that HTML elements defined in theelements
property may contain classes, styles or attributes that are created by other plugins. For example,implements
equal to$block
means that HTML elements may contain classes, styles or attributes that are defined by another plugin, which haselements
equal to$block
.isAlternative
– If the plugin output depends on its configuration, this value should be set totrue
to mark outputs that are not produced by the default configuration. If this value is either missing orfalse
, the output will be considered as default output._comment
– A human-readable description to explain more complicated cases, for example: the conditions when a given element, class or style can be created.
Below is an example showing how the Bold
plugin can be documented using this format:
{
"name": "Bold",
"className": "Bold",
"description": "Implements bold formatting support. It is a part of the basic text styles package.",
"docs": "features/basic-styles.html",
"path": "src/bold.js",
"uiComponents": [
{
"type": "Button",
"name": "bold",
"iconPath": "theme/icons/bold.svg"
}
],
"htmlOutput": [
{
"elements": "strong"
}
]
}
If you want to check how plugins are documented in other packages, visit the CKEditor 5 packages section on GitHub and find the ckeditor5-metadata.json
file in a package you are interested in.
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.