Skip to content

Commit

Permalink
Merge pull request #9685 from ckeditor/i/6642
Browse files Browse the repository at this point in the history
Other: Add plugins metadata to packages. Introduce guides for the metadata and present HTML output of features. Closes #6642.
  • Loading branch information
ma2ciek authored May 13, 2021
2 parents dbc9133 + 7ecc448 commit cad8a72
Show file tree
Hide file tree
Showing 45 changed files with 4,436 additions and 2 deletions.
2,182 changes: 2,182 additions & 0 deletions docs/builds/guides/integration/features-html-output-overview.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
category: framework-contributing
order: 40
order: 50
---

# Git commit message convention
Expand Down
63 changes: 63 additions & 0 deletions docs/framework/guides/contributing/package-metadata.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
category: framework-contributing
order: 40
---

# Package metadata

The package metadata is a set of CKEditor 5-related data describing plugins that the package delivers. It allows for an automated detection of plugins and building them by an external builder - e.g. by the [CKEditor 5 Online Builder](https://ckeditor.com/ckeditor-5/online-builder/) and building the {@link builds/guides/integration/features-html-output-overview features HTML output overview} page presenting all CKEditor 5 plugins. This data should be saved in the special `ckeditor5-metadata.json` file in the root of the package published on NPM.

<info-box>
Only plugins that provide major functionalities should be described in the metadata file. For example, [the metadata file for the `@ckeditor/ckeditor5-mention` package](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-mention/ckeditor5-metadata.json) 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 `MentionEditing` and `MentionUI` plugins that cannot be used alone.
</info-box>

## 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` &ndash; A human-readable name of the plugin.
* `description` &ndash; A human-readable short description of the plugin.
* `docs` &ndash; An absolute or relative URL to the plugin's documentation. If this URL is relative, it leads to the CKEditor 5 documentation in [https://ckeditor.com/docs/ckeditor5/latest/](https://ckeditor.com/docs/ckeditor5/latest/).
* `path` &ndash; A path to the file, relative to the metadata file that exports the plugin.
* `className` &ndash; The name of the class used to create the plugin. This class should be exported from the file using the `export default` syntax.
* `requires` &ndash; 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.
* `registeredToolbars` &ndash; An array of all toolbar names registered by the plugin. These names need to represent the configuration path (e.g. `table.contentToolbar` for `editorConfig.table.contentToolbar` and `table.tableToolbar` for the `editorConfig.table.tableToolbar`, which are registered by the `Table` plugin).
* `uiComponents` &ndash; An array of objects, that describes UI components exported by the plugin. Each object in this array may contain:
* `name` &ndash; A name of the component the plugin exports. It should match the actual UI name registered by the plugin.
* `type` &ndash; Component type: `Button`, `SplitButton` or `Dropdown`.
* `iconPath` &ndash; A path to the SVG icon for `Button` or `SplitButton`. The path can be either relative to the package or absolute - linking to a resource from another package.
* `label` &ndash; Text content for `Dropdown` components.
* `toolbars` &ndash; An array of toolbar names, a given UI component can be added to. Some UI components may be added to multiple toolbars.
* `htmlOutput` &ndash; An array of objects, that defines all possible HTML elements which can be created by a given plugin. The main property in this object is `elements`. Other properties (e.g. `classes`, `styles`, `attributes`) only apply to items defined in the `elements` property within a given object. Wildcard character `*` is used to mark any value. Full list of all these properties includes:
* `elements` &ndash; 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` &ndash; CSS class names (a single one or an array of these) that may be applied to the HTML elements defined in the `elements` property.
* `styles` &ndash; Inline CSS styles (a single one or an array of these) that may be applied to the HTML elements defined in the `elements` property.
* `attributes` &ndash; HTML attributes (a single one or an array of these) other than `class` and `styles` (covered separately), that might be applied to the HTML elements defined in the `elements` property.
* `implements` &ndash; A name of an element or a pseudo-element which indicates that HTML elements defined in the `elements` 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 has `elements` equal to `$block`.
* `_comment` &ndash; 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:

```json
{
"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](https://github.com/ckeditor/ckeditor5/tree/master/packages) section on GitHub and find the `ckeditor5-metadata.json` file in a package you are interested in.
4 changes: 3 additions & 1 deletion docs/framework/guides/creating-simple-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -295,4 +295,6 @@ If you would like to read more tutorials, check out the following one:
* {@link framework/guides/tutorials/implementing-a-block-widget Implementing a block widget}
* {@link framework/guides/tutorials/implementing-an-inline-widget Implementing an inline widget}

If you are more into reading about the CKEditor 5 architecture, check out the {@link framework/guides/architecture/intro Introduction to CKEditor 5 architecture}.
If you want to read more about the CKEditor 5 architecture, check out the {@link framework/guides/architecture/intro Introduction to CKEditor 5 architecture} guide.

If you want your plugin to be easily integrated by other developers, learn about the {@link framework/guides/contributing/package-metadata package metadata file} that can be added to your package.
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,7 @@
"docs:build-and-publish": "node ./scripts/docs/build-and-publish.js",
"docs:build-and-publish-nightly": "node ./scripts/docs/build-and-publish-nightly.js",
"docs:content-styles": "node ./scripts/docs/build-content-styles.js",
"docs:features-html-output": "node ./scripts/docs/features-html-output/build-features-html-output.js",
"docs:serve": "http-server ./build/docs/",
"docs:verify": "node ./scripts/web-crawler/index.js --docs",
"translations:collect": "ckeditor5-dev-env-translations collect",
Expand Down
11 changes: 11 additions & 0 deletions packages/ckeditor5-adapter-ckfinder/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"plugins": [
{
"name": "CKFinder Upload Adapter",
"className": "CKFinderUploadAdapter",
"path": "src/uploadadapter.js",
"description": "This package implements a CKEditor 5 upload adapter compatible with the CKFinder file manager and uploader's server–side connector.",
"docs": "features/image-upload/image-upload.html#ckfinder"
}
]
}
30 changes: 30 additions & 0 deletions packages/ckeditor5-alignment/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"plugins": [
{
"name": "Alignment",
"className": "Alignment",
"path": "src/alignment.js",
"description": "Enables support for text alignment. You can use it to align your content to left, right and center or to justify it.",
"docs": "features/image-upload/image-upload.html#ckfinder",
"uiComponents": [
{
"type": "SplitButton",
"name": "alignment",
"iconPath": "@ckeditor/ckeditor5-core/theme/icons/align-left.svg"
}
],
"htmlOutput": [
{
"elements": "$block",
"styles": "text-align",
"_comment": "By default, the alignment is set inline using `text-align` CSS property."
},
{
"elements": "$block",
"classes": "*",
"_comment": "If class names are defined in `config.alignment.options`, then these classes are used for alignment instead of inline styles."
}
]
}
]
}
11 changes: 11 additions & 0 deletions packages/ckeditor5-autoformat/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"plugins": [
{
"name": "Autoformat",
"className": "Autoformat",
"description": "Enables a set of predefined autoformatting actions. It allows for formatting text by typing sequences like **bold this**.",
"docs": "features/autoformat.html",
"path": "src/autoformat.js"
}
]
}
11 changes: 11 additions & 0 deletions packages/ckeditor5-autosave/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"plugins": [
{
"name": "Autosave",
"className": "Autosave",
"description": "Allows you to automatically save the data (e.g. send it to the server) when needed, for example, when the user changed the content.",
"docs": "builds/guides/integration/saving-data.html#autosave-feature",
"path": "src/autosave.js"
}
]
}
138 changes: 138 additions & 0 deletions packages/ckeditor5-basic-styles/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
{
"plugins": [
{
"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"
}
]
},
{
"name": "Code",
"className": "Code",
"description": "Implements inline code formatting support. It is a part of the basic text styles package.",
"docs": "features/basic-styles.html",
"path": "src/code.js",
"uiComponents": [
{
"type": "Button",
"name": "code",
"iconPath": "theme/icons/code.svg"
}
],
"htmlOutput": [
{
"elements": "code",
"classes": "ck-code_selected"
}
]
},
{
"name": "Italic",
"className": "Italic",
"description": "Implements italic formatting support. It is a part of the basic text styles package.",
"docs": "features/basic-styles.html",
"path": "src/italic.js",
"uiComponents": [
{
"type": "Button",
"name": "italic",
"iconPath": "theme/icons/italic.svg"
}
],
"htmlOutput": [
{
"elements": "i"
}
]
},
{
"name": "Strikethrough",
"className": "Strikethrough",
"description": "Implements strikethrough formatting support. It is a part of the basic text styles package.",
"docs": "features/basic-styles.html",
"path": "src/strikethrough.js",
"uiComponents": [
{
"type": "Button",
"name": "strikethrough",
"iconPath": "theme/icons/strikethrough.svg"
}
],
"htmlOutput": [
{
"elements": "s"
}
]
},
{
"name": "Subscript",
"className": "Subscript",
"description": "Implements subscript formatting support. It is a part of the basic text styles package.",
"docs": "features/basic-styles.html",
"path": "src/subscript.js",
"uiComponents": [
{
"type": "Button",
"name": "subscript",
"iconPath": "theme/icons/subscript.svg"
}
],
"htmlOutput": [
{
"elements": "sub"
}
]
},
{
"name": "Superscript",
"className": "Superscript",
"description": "Implements superscript formatting support. It is a part of the basic text styles package.",
"docs": "features/basic-styles.html",
"path": "src/superscript.js",
"uiComponents": [
{
"type": "Button",
"name": "superscript",
"iconPath": "theme/icons/superscript.svg"
}
],
"htmlOutput": [
{
"elements": "sup"
}
]
},
{
"name": "Underline",
"className": "Underline",
"description": "Implements underline formatting support. It is a part of the basic text styles package.",
"docs": "features/basic-styles.html",
"path": "src/underline.js",
"uiComponents": [
{
"type": "Button",
"name": "underline",
"iconPath": "theme/icons/underline.svg"
}
],
"htmlOutput": [
{
"elements": "u"
}
]
}
]
}
23 changes: 23 additions & 0 deletions packages/ckeditor5-block-quote/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"plugins": [
{
"name": "Block quote",
"className": "BlockQuote",
"description": "Implements block quote support to easily include quotations and passages in the rich-text content.",
"docs": "features/block-quote.html",
"path": "src/blockquote.js",
"uiComponents": [
{
"type": "Button",
"name": "blockQuote",
"iconPath": "@ckeditor/ckeditor5-core/theme/icons/quote.svg"
}
],
"htmlOutput": [
{
"elements": "blockquote"
}
]
}
]
}
23 changes: 23 additions & 0 deletions packages/ckeditor5-ckfinder/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"plugins": [
{
"name": "CKFinder",
"className": "CKFinder",
"description": "An image upload tool. It provides a full, server-side and client-side integration with CKFinder and all its features, including multiple file upload, image editor and file management.",
"docs": "features/image-upload/ckfinder.html",
"path": "src/ckfinder.js",
"requires": [
"CKFinderUploadAdapter",
"Link",
"Image"
],
"uiComponents": [
{
"name": "CKFinder",
"type": "Button",
"iconPath": "theme/icons/browse-files.svg"
}
]
}
]
}
11 changes: 11 additions & 0 deletions packages/ckeditor5-cloud-services/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"plugins": [
{
"name": "Cloud Services",
"className": "CloudServices",
"description": "A set of tools to work with CKEditor 5 Cloud Services.",
"path": "src/cloudservices.js",
"docs": "https://ckeditor.com/ckeditor-cloud-services"
}
]
}
31 changes: 31 additions & 0 deletions packages/ckeditor5-code-block/ckeditor5-metadata.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
{
"plugins": [
{
"name": "Code blocks",
"className": "CodeBlock",
"description": "Allows for inserting and editing blocks of pre–formatted code with the programming language assigned.",
"docs": "features/code-blocks.html",
"path": "src/codeblock.js",
"uiComponents": [
{
"type": "Button",
"name": "codeBlock",
"iconPath": "theme/icons/codeblock.svg"
}
],
"htmlOutput": [
{
"elements": "pre"
},
{
"elements": "code",
"classes": [
"*",
"language-*"
],
"_comment": "By default, the language of the code block is represented as a CSS class prefixed by `language-`. CSS class name can be customized via `config.codeBlock.languages` array."
}
]
}
]
}
Loading

0 comments on commit cad8a72

Please sign in to comment.