Merge pull request #9685 from ckeditor/i/6642

Other: Add plugins metadata to packages. Introduce guides for the metadata and present HTML output of features. Closes #6642.

docs/framework/guides/contributing/git-commit-message-convention.md

@@ -1,6 +1,6 @@
 ---
 category: framework-contributing
-order: 40
+order: 50
 ---
 
 # Git commit message convention

docs/framework/guides/contributing/package-metadata.md

@@ -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.

docs/framework/guides/creating-simple-plugin.md

@@ -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.

package.json

@@ -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",

packages/ckeditor5-adapter-ckfinder/ckeditor5-metadata.json

@@ -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"
+		}
+	]
+}

packages/ckeditor5-alignment/ckeditor5-metadata.json

@@ -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."
+				}
+			]
+		}
+	]
+}

packages/ckeditor5-autoformat/ckeditor5-metadata.json

@@ -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"
+		}
+	]
+}

packages/ckeditor5-autosave/ckeditor5-metadata.json

@@ -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"
+		}
+	]
+}

packages/ckeditor5-basic-styles/ckeditor5-metadata.json

@@ -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"
+				}
+			]
+		}
+	]
+}

packages/ckeditor5-block-quote/ckeditor5-metadata.json

@@ -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"
+				}
+			]
+		}
+	]
+}

packages/ckeditor5-ckfinder/ckeditor5-metadata.json

@@ -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"
+				}
+			]
+		}
+	]
+}

packages/ckeditor5-cloud-services/ckeditor5-metadata.json

@@ -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"
+		}
+	]
+}

packages/ckeditor5-code-block/ckeditor5-metadata.json

@@ -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."
+				}
+			]
+		}
+	]
+}