Add documentation for link decorators.

docs/_snippets/features/linkdecorators.html

@@ -0,0 +1,14 @@
+<div id="snippet-link-decorators">
+	<h2>Links list</h2>
+	<ol>
+		<li>
+			<a href="https://ckeditor.com">Link to external page</a>
+		</li>
+		<li>
+			<a href="/">Link to internal page</a>
+		</li>
+	</ol>
+</div>
+<pre class="highlight">
+	<code class="html hljs" id="output-link-decorators"></code>
+</pre>

docs/_snippets/features/linkdecorators.js

@@ -0,0 +1,73 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals console, window, document, Worker, setTimeout */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-link-decorators' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'link',
+				'bulletedList',
+				'numberedList',
+				'blockQuote',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		link: {
+			targetDecorator: true,
+			decorators: [
+				{
+					mode: 'manual',
+					label: 'Downloadable',
+					attributes: {
+						download: 'download'
+					}
+				}
+			]
+		}
+	} )
+	.then( editor => {
+		if ( !window.editors ) {
+			window.editors = {};
+		}
+		window.editors.decorators = editor;
+
+		const outputElement = document.querySelector( '#output-link-decorators' );
+		const worker = new Worker( window.umberto.relativeAppPath + '/highlight.worker.js' );
+
+		worker.addEventListener( 'message', evt => {
+			const data = JSON.parse( evt.data );
+
+			outputElement.innerHTML = data.payload;
+		} );
+
+		editor.model.document.on( 'change', () => {
+			worker.postMessage( JSON.stringify( {
+				payload: editor.getData(),
+				language: 'html'
+			} ) );
+		} );
+
+		setTimeout( () => {
+			worker.postMessage( JSON.stringify( {
+				payload: editor.getData(),
+				language: 'html'
+			} ) );
+		}, 500 );
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

docs/features/link.md

@@ -23,6 +23,66 @@ CKEditor 5 allows for typing both at inner and outer boundaries of links to make
 
 {@img assets/img/typing-before.gif 770 The animation showing typing before the link in CKEditor 5 rich text editor.}
 
+## Link decorators
+
+Link decorators is a feature that allows on extending HTML anchor with custom predefined attributes. There are 2 types of decorators: "automatic" and "manual". More information about each of them might be found in sections below. There might be applied multiple decorators to the same link (including manual and automatic decorators in one editor).
+<info-box warning>
+	**Warning:** It is not recommended to modify the same attribute through two or more decorators. All decorators works independent and its state is not reflected between them in any way. This also includes mixing manual and automatic decorators.
+</info-box>
+
+{@snippet features/linkdecorators}
+
+### Automatic decorators
+
+These types of decorators work during downcasting data ({@link framework/guides/architecture/editing-engine#conversion read more about conversion}). You can specify your own rules as a callback function. Function gets a link's href as an input argument and when the callback function returns `true`, then given attributes are applied for a processed link. There might be applied multiple rules for the same link, however you should never process the same attribute through different decorators. Rules how to define automatic decorators can be found in {@linkapi module:link/link~LinkDecoratorAutomaticOption automatic decorator definition}.
+
+For example this decorator will add `download="download"` attribute to every link ending with `.pdf`:
+```js
+const config = {
+	link: {
+		decorators: [
+			{
+				mode: 'automatic',
+				callback: url => url.endsWith( '.pdf' ),
+				attributes: {
+					download: 'download'
+				}
+			}
+		]
+	}
+}
+```
+
+#### Target decorator
+
+There is also predefined configuration option {@linkapi module:link/link~LinkConfig#targetDecorator} which adds automatic decorator. This decorator adds two attributes ( `target="_blank"` and `rel="noopener noreferrer"` ) to all external links.
+Target decorator comes with followed configuration underneath:
+```js
+{
+	mode: 'automatic',
+	callback: url => /^(https?:)?\/\//.test( url ),
+	attributes: {
+		target: '_blank',
+		rel: 'noopener noreferrer'
+	}
+}
+```
+
+### Manual decorators
+
+These types of decorators adds switch button in user interface, which allows on toggling predefined attributes over a link. Switch buttons are visible in editing option of a link and requires applying changes to be set up over the link. Manual decorators doesn't have a callback property and are available for every link in editor. There is required `label` property, which is using as label for switch button in UI.
+
+For example this decorator will add "Downloadable" switch button:
+```js
+{
+	mode: 'manual',
+	label: 'Downloadable',
+	attributes: {
+		download: 'download'
+	}
+}
+```
+
 ## Installation
 
 <info-box info>