8
0
Pārlūkot izejas kodu

Merge branch 'master' into t/migration-review

Piotrek Koszuliński 7 gadi atpakaļ
vecāks
revīzija
df97c2c389

+ 46 - 0
CHANGELOG.md

@@ -1,6 +1,52 @@
 Changelog
 =========
 
+## [1.0.0-beta.1](https://github.com/ckeditor/ckeditor5/compare/v1.0.0-alpha.2...v1.0.0-beta.1) (2018-03-15)
+
+### Dependencies
+
+New packages:
+
+* [@ckeditor/ckeditor5-alignment](https://www.npmjs.com/package/@ckeditor/ckeditor5-alignment): [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-alignment/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-build-decoupled-document](https://www.npmjs.com/package/@ckeditor/ckeditor5-build-decoupled-document): [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-build-decoupled-document/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-editor-decoupled](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-decoupled): [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-editor-decoupled/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-font](https://www.npmjs.com/package/@ckeditor/ckeditor5-font): [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-font/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-highlight](https://www.npmjs.com/package/@ckeditor/ckeditor5-highlight): [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-highlight/releases/tag/v1.0.0-beta.1)
+
+Major releases (contain breaking changes):
+
+* [@ckeditor/ckeditor5-adapter-ckfinder](https://www.npmjs.com/package/@ckeditor/ckeditor5-adapter-ckfinder): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-adapter-ckfinder/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-autoformat](https://www.npmjs.com/package/@ckeditor/ckeditor5-autoformat): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-autoformat/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-basic-styles](https://www.npmjs.com/package/@ckeditor/ckeditor5-basic-styles): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-basic-styles/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-block-quote](https://www.npmjs.com/package/@ckeditor/ckeditor5-block-quote): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-block-quote/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-build-balloon](https://www.npmjs.com/package/@ckeditor/ckeditor5-build-balloon): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-build-balloon/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-build-classic](https://www.npmjs.com/package/@ckeditor/ckeditor5-build-classic): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-build-classic/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-build-inline](https://www.npmjs.com/package/@ckeditor/ckeditor5-build-inline): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-build-inline/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-clipboard](https://www.npmjs.com/package/@ckeditor/ckeditor5-clipboard): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-clipboard/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-cloudservices](https://www.npmjs.com/package/@ckeditor/ckeditor5-cloudservices): v1.0.0-alpha.1 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-cloudservices/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-core](https://www.npmjs.com/package/@ckeditor/ckeditor5-core): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-core/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-easy-image](https://www.npmjs.com/package/@ckeditor/ckeditor5-easy-image): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-easy-image/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-editor-balloon](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-balloon): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-editor-balloon/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-editor-classic](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-classic): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-editor-classic/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-editor-inline](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-inline): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-editor-inline/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-engine/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-enter](https://www.npmjs.com/package/@ckeditor/ckeditor5-enter): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-enter/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-essentials](https://www.npmjs.com/package/@ckeditor/ckeditor5-essentials): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-essentials/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-heading](https://www.npmjs.com/package/@ckeditor/ckeditor5-heading): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-heading/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-image](https://www.npmjs.com/package/@ckeditor/ckeditor5-image): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-image/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-link](https://www.npmjs.com/package/@ckeditor/ckeditor5-link): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-link/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-list](https://www.npmjs.com/package/@ckeditor/ckeditor5-list): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-list/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-markdown-gfm](https://www.npmjs.com/package/@ckeditor/ckeditor5-markdown-gfm): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-markdown-gfm/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-paragraph](https://www.npmjs.com/package/@ckeditor/ckeditor5-paragraph): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-paragraph/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-theme-lark](https://www.npmjs.com/package/@ckeditor/ckeditor5-theme-lark): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-theme-lark/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-typing](https://www.npmjs.com/package/@ckeditor/ckeditor5-typing): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-typing/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-ui/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-undo](https://www.npmjs.com/package/@ckeditor/ckeditor5-undo): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-undo/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-upload](https://www.npmjs.com/package/@ckeditor/ckeditor5-upload): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-upload/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-utils/releases/tag/v1.0.0-beta.1)
+* [@ckeditor/ckeditor5-widget](https://www.npmjs.com/package/@ckeditor/ckeditor5-widget): v1.0.0-alpha.2 => [v1.0.0-beta.1](https://github.com/ckeditor/ckeditor5-widget/releases/tag/v1.0.0-beta.1)
+
+
 ## [1.0.0-alpha.2](https://github.com/ckeditor/ckeditor5.git/compare/v1.0.0-alpha.1...v1.0.0-alpha.2) (2017-11-14)
 
 ### Dependencies

+ 6 - 1
docs/_snippets/examples/document-editor.html

@@ -45,7 +45,7 @@
 
 	.document-editor__editable .ck-editor__editable {
 		/* Set the dimensions of the "page". */
-		width: 15.8cm;
+		width: 15cm;
 		min-height: 21cm;
 
 		/* Keep the "page" off the boundaries of the container. */
@@ -62,6 +62,11 @@
 		margin: 0 auto;
 	}
 
+	/* Override the page's width in the "Examples" section which is wider. */
+	.main__content-wide .document-editor__editable .ck-editor__editable {
+		width: 18cm;
+	}
+
 	/* Set the default font for the "page" of the content. */
 	.document-editor .ck-content,
 	.document-editor .ck-heading-dropdown .ck-list {

+ 2 - 2
docs/_snippets/examples/document-editor.js

@@ -10,8 +10,8 @@ import { CS_CONFIG } from '@ckeditor/ckeditor5-cloudservices/tests/_utils/clouds
 
 DecoupledDocumentEditor
 	.create( document.querySelector( '.document-editor__data' ).innerHTML, {
-		toolbarContainer: '.document-editor__toolbar',
-		editableContainer: '.document-editor__editable',
+		toolbarContainer: document.querySelector( '.document-editor__toolbar' ),
+		editableContainer: document.querySelector( '.document-editor__editable' ),
 
 		cloudServices: CS_CONFIG
 	} )

+ 1 - 1
docs/_snippets/features/read-only.html

@@ -3,5 +3,5 @@
 </p>
 
 <div id="snippet-read-only">
-	<p>This is <a href="https://ckeditor5.github.io">CKEditor&nbsp;5</a>.</p>
+	<p>This is <a href="https://ckeditor.com">CKEditor&nbsp;5</a>.</p>
 </div>

+ 1 - 1
docs/_snippets/features/ui-language.html

@@ -1,3 +1,3 @@
 <div id="snippet-ui-language">
-	<p>This is <a href="https://ckeditor5.github.io">CKEditor&nbsp;5</a>.</p>
+	<p>This is <a href="https://ckeditor.com">CKEditor&nbsp;5</a>.</p>
 </div>

+ 13 - 0
docs/assets/snippet-styles.css

@@ -61,6 +61,19 @@ It breaks CKEditor 5 (see how <p><code>[]</code></p> looks). */
 	margin-bottom: 1.5rem;
 }
 
+/* https://github.com/ckeditor/ckeditor5/issues/896 */
+.live-snippet .ck-content h2,
+.live-snippet .ck-content h3,
+.live-snippet .ck-content h4 {
+	position: static;
+}
+
+/* https://github.com/ckeditor/ckeditor5/issues/899 */
+.live-snippet .ck-dropdown .ck-list {
+	margin: 0;
+	padding: 0;
+}
+
 #snippet-inline-editor .ck-editor__editable {
 	margin-bottom: 1rem;
 	padding: 2rem;

+ 21 - 0
docs/assets/styles.css

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ */
+
+/* https://github.com/ckeditor/ckeditor5/issues/913 */
+@media only screen and (min-width: 1600px) {
+	.main .main__content-wide .main__content-inner {
+		width: 800px;
+	}
+}
+
+/* https://github.com/ckeditor/ckeditor5/issues/913 */
+@media only screen and (min-width: 1360px) {
+	.main .main__content.main__content-wide {
+		padding-right: 0;
+	}
+
+	.main .main__content-wide .main__content-inner {
+		max-width: 800px;
+	}
+}

+ 108 - 0
docs/builds/guides/faq.md

@@ -0,0 +1,108 @@
+---
+menu-title: FAQ
+category: builds-guides
+order: 40
+---
+
+# Frequently asked questions
+
+## Why the editor filters out my content (styles, classes, elements)? Where is `config.allowedContent = true`?
+
+Unlike [CKEditor 4](https://ckeditor.com/ckeditor-4/), CKEditor 5 implements a custom {@link framework/guides/architecture/editing-engine data model}. This means that every piece of content that is loaded into the editor needs to be converted to that model and then rendered back to the view.
+
+Each kind of content must be handled by some feature. For instance the [ckeditor5-basic-styles](https://www.npmjs.com/package/@ckeditor/ckeditor5-basic-styles) package handles HTML like `<b>`, `<i>`, `<u>`, etc. along with their representation in the model. The feature defines the two–way conversion between the HTML (view) and the editor model.
+
+If you load a content unknown to any editor feature, it will be dropped. If you want all the HTML5 elements to be supported, you need to write plugins to support them. Once you do that, CKEditor 5 won't filter anything out.
+
+## How to turn the source mode on? How to write a source mode plugin?
+
+Because of the custom {@link framework/guides/architecture/editing-engine data model} used in the editor, the source mode makes little sense in CKEditor 5. CKEditor 5 is a content editor, <strong>not</strong> a page builder and, unless some editor feature (plugin) supports some particular kind of HTML (or any other input format), it will not be accepted as a content.
+
+See the [issue](https://github.com/ckeditor/ckeditor5/issues/592) on GitHub to learn more.
+
+## What happened to the `contents.css` file? How do I style the content of the editor?
+
+There's no such thing as the `contents.css` file because in CKEditor 5 features brings their own content styles, which are by default included in the JavaScript build and {@link framework/guides/theme-customization#styles-processing-and-bundling loaded by the style–loader} (they can be  {@link builds/guides/integration/advanced-setup#option-extracting-css extracted} too). It optimizes the size of the builds as the styles of unused features are simply excluded.
+
+Although some styles are provided by the features, it is up to the developers to make sure the content created by CKEditor 5 is properly styled, both in the front–end and in the back–end. To style the content in the editor (back–end), use the `.ck-content` CSS class:
+
+```css
+.ck-content a {
+	color: teal;
+}
+```
+
+## The build I downloaded is missing some features. How to add them?
+
+See the {@link builds/guides/development/installing-plugins "Installing plugins"} guide to learn how to extend the editor with some additional features.
+
+You can learn which editor are available in the {@link features/index feature index}.
+
+## Where are the `editor.insertHtml()` and `editor.insertText()` methods? How to insert some content?
+
+Because CKEditor 5 uses the custom {@link framework/guides/architecture/editing-engine data model}, whenever you want to insert anything, you should modify the model first, which is then converted back to the view where users input their content (called editable). In CKEditor 5, HTML is just one of many possible output formats. You can learn more about the ways of changing the model in the {@link framework/guides/architecture/editing-engine#changing-the-model dedicated guide}.
+
+To insert a new link at the current selection, use the following snippet:
+
+```js
+editor.model.change( writer => {
+    const insertPosition = editor.model.document.selection.getFirstPosition();
+    writer.insertText( 'CKEditor 5 rocks!', { linkHref: 'https://ckeditor.com/' }, insertPosition );
+} );
+```
+
+and to insert some plain text, you can use a slightly shorter one:
+
+```js
+editor.model.change( writer => {
+    writer.insertText( 'Plain text', editor.model.document.selection.getFirstPosition() );
+} );
+```
+
+You may have noticed that link is represented as a text with an attribute in the editor model. See the API of the {@link module:engine/model/writer~Writer model writer} to learn about other useful methods that can help you modify the editor model.
+
+To insert some longer HTML, you can parse it to the {@link module:engine/model/documentfragment~DocumentFragment model fragment} first and then {@link module:engine/model/model~Model#insertContent insert} it into the editor model:
+
+```js
+const content = '<p>A paragraph with <a href="https://ckeditor.com">some link</a>.';
+const viewFragment = editor.data.processor.toView( content );
+const modelFragment = editor.data.toModel( viewFragment );
+
+editor.model.insertContent( modelFragment, editor.model.document.selection );
+```
+
+## What happened to the global `window.CKEDITOR`? How to list all instances of the editor?
+
+By default, CKEditor 5 has no global registry of editor instances. But if necessary, such feature can be easily implemented as explained in the [Stack Overflow answer](https://stackoverflow.com/a/48682501/1485219).
+
+## How to enable image drag&drop and upload? Where should I start?
+
+Image features are enabled by default in all editor builds (also the image upload). See the {@link features/image image} and {@link features/image-upload image upload} feature guides to learn more.
+
+## How to use CKEditor 5 with frameworks (Angular, React, etc.)?
+
+There are no ready–to–use framework adapters as of yet. We recognize the popularity of these frameworks and our intention is for the guides and seamless integrations to be developed in the future. In the meanwhile, please check out the [GitHub issue](https://github.com/ckeditor/ckeditor5/issues/599) for more information.
+
+## How to get a fully–featured editor build (a.k.a. CKEditor 4 "Full Package")?
+
+We believe each editor build should serve its purpose. Including features that are not used makes little sense because they increase the size of the editor and make the website heavier for no good reason. This is why we do not provide a full editor package similar to what we offer in CKEditor 4.
+
+At the same time, we recommend you to {@link builds/guides/development/installing-plugins install plugins} to enable {@link features/index additional features} or even create a {@link builds/guides/development/custom-builds custom build} to make sure you make most of CKEditor 5.
+
+## How to customize the CKEditor 5 icons?
+
+The easiest way is to use Webpack's [`NormalModuleReplacementPlugin`](https://webpack.js.org/plugins/normal-module-replacement-plugin/) plugin. To replace the bold icon use the following code in your `webpack.config.js`:
+
+```js
+...
+plugins: [
+	new webpack.NormalModuleReplacementPlugin(
+		/bold\.svg/,
+		'/absolute/path/to/my/icon.svg'
+	)
+]
+```
+
+You can also use the relative path which is resolved relative to the resource that imports `bold.svg` (the {@link module:basic-styles/bold/boldui~BoldUI `BoldUI`} class file in this scenario).
+
+Learn more about {@link builds/guides/integration/advanced-setup#webpack-configuration building CKEditor 5 using Webpack}.

+ 7 - 2
docs/builds/guides/integration/advanced-setup.md

@@ -88,14 +88,19 @@ The second step is to install dependencies needed to build the editor. The list
 ```bash
 npm install --save \
 	@ckeditor/ckeditor5-dev-webpack-plugin \
+	@ckeditor/ckeditor5-dev-utils \
 	postcss-loader \
 	raw-loader \
 	style-loader \
-	webpack
+	webpack@^3.11.0
 ```
 
 You may also want to install [`babel-minify-webpack-plugin`](https://github.com/webpack-contrib/babel-minify-webpack-plugin) if you plan to minify ES6+ code.
 
+<info-box warning>
+	Unfortunately, at the moment of writing this note, [webpack@4.x causes issues](https://github.com/ckeditor/ckeditor5-dev/issues/371).
+</info-box>
+
 ### Webpack configuration
 
 Now, you can configure webpack. There are a couple of things which you need to take care of when building CKEditor:
@@ -115,7 +120,7 @@ module.exports = {
 		// ...
 
 		new CKEditorWebpackPlugin( {
-			// See https://ckeditor5.github.io/docs/nightly/ckeditor5/latest/features/ui-language.html
+			// See https://docs.ckeditor.com/ckeditor5/latest/features/ui-language.html
 			language: 'pl'
 		} )
 	],

+ 3 - 0
docs/builds/guides/integration/installation.md

@@ -36,6 +36,8 @@ npm install --save @ckeditor/ckeditor5-build-classic
 npm install --save @ckeditor/ckeditor5-build-inline
 # Or:
 npm install --save @ckeditor/ckeditor5-build-balloon
+# Or:
+npm install --save @ckeditor/ckeditor5-build-decoupled-document
 ```
 
 CKEditor will then be available at `node_modules/@ckeditor/ckeditor5-build-[name]/build/ckeditor.js`. It can also be imported directly to your code by `require( '@ckeditor/ckeditor5-build-[name]' )`.
@@ -50,6 +52,7 @@ Extract the `.zip` file into a dedicated directory inside your project. It is re
 
 * `ckeditor.js` – the ready-to-use editor bundle, containing the editor and all plugins.
 * `ckeditor.js.map` – the source map for the editor bundle.
+* `translations/` – editor UI translations (see {@link features/ui-language Setting UI language}).
 * `README.md` and `LICENSE.md`
 
 ## Loading the API

+ 4 - 6
docs/builds/guides/quick-start.md

@@ -194,9 +194,8 @@ The decoupled editor requires you to define the containers for the toolbar and e
 	DecoupledDocumentEditor
 		.create( '<p>The initial editor data</p>', {
 			// Define the containers for the toolbar and editable.
-			// Use the document.querySelector-friendly strings here or references to existing DOM elements.
-			toolbarContainer: '.toolbar-container',
-			editableContainer: '.editable-container'
+			toolbarContainer: document.querySelector( '.toolbar-container' ),
+			editableContainer: document.querySelector( '.editable-container' )
 		} )
 		.catch( error => {
 			console.error( error );
@@ -227,9 +226,8 @@ The decoupled editor requires you to define the containers for the toolbar and e
 		DecoupledDocumentEditor
 			.create( '<p>The initial editor data</p>', {
 				// Define the containers for the toolbar and editable.
-				// Use the document.querySelector-friendly strings here or references to existing DOM elements.
-				toolbarContainer: '.toolbar-container',
-				editableContainer: '.editable-container'
+				toolbarContainer: document.querySelector( '.toolbar-container' ),
+				editableContainer: document.querySelector( '.editable-container' )
 			} )
 			.catch( error => {
 				console.error( error );

+ 2 - 0
docs/examples/builds/document-editor.md

@@ -1,6 +1,7 @@
 ---
 category: examples-builds
 order: 30
+classes: main__content-wide
 ---
 
 # Document editor
@@ -10,3 +11,4 @@ The editor in this example is a feature–rich build focused on rich text editin
 See the {@link framework/guides/document-editor tutorial} to learn how to create this kind of an editor (and similar) with a custom UI layout on top of {@link module:editor-decoupled/decouplededitor~DecoupledEditor}.
 
 {@snippet examples/document-editor}
+

+ 2 - 0
docs/features/image-upload.md

@@ -54,6 +54,8 @@ To make enabling image upload in CKEditor 5 a breeze, by default all builds incl
 
 This is all. At this point, image upload will be automatically enabled in your application.
 
+If you're having troubles in setting up Easy Image, please [contact us](https://ckeditor.com/contact/).
+
 ### Demo
 
 The demo below uses the {@link builds/guides/overview#classic-editor Classic editor} configured (like above) to use the Easy Image service provided by CKEditor Cloud Services:

+ 16 - 7
docs/features/ui-language.md

@@ -1,6 +1,5 @@
 ---
 category: features
-toc: false
 ---
 
 # Setting the UI language
@@ -15,16 +14,18 @@ See the demo of the editor in German:
 
 ## Loading additional languages from CDN, npm and zip file
 
-You can load additional languages using:
+ By default, the editor will display in English. This is the language built into the `ckeditor.js` files. In order to change the language of the editor UI, you need to load additional language file(s). Check out the following sections to see how to do that:
+
 * [CDN](#cdn),
 * [npm](#npm),
 * [Zip download](#zip).
 
-Next, configure the editor to use chosen language:
+Next, you can configure the editor to use the chosen language:
 
 ```js
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
+		// The language code is defined in the https://en.wikipedia.org/wiki/ISO_639-1 standard.
 		language: 'de'
 	} )
 	.then( editor => {
@@ -41,7 +42,14 @@ To use different language than default one (English), you need to load the edito
 
 ```html
 <script src="https://cdn.ckeditor.com/ckeditor5/[version.number]/[distribution]/ckeditor.js"></script>
-<script src="https://cdn.ckeditor.com/ckeditor5/[version.number]/[distribution]/translations/de.js"></script>
+<script src="https://cdn.ckeditor.com/ckeditor5/[version.number]/[distribution]/translations/[lang].js"></script>
+```
+
+For example:
+
+```html
+<script src="https://cdn.ckeditor.com/ckeditor5/{@var ckeditor5-version}/classic/ckeditor.js"></script>
+<script src="https://cdn.ckeditor.com/ckeditor5/{@var ckeditor5-version}/classic/translations/de.js"></script>
 ```
 
 See {@link builds/guides/integration/installation#cdn CDN installation guides} for more information.
@@ -49,15 +57,16 @@ See {@link builds/guides/integration/installation#cdn CDN installation guides} f
 ### npm
 
 After installing the build from npm, languages will be available at `node_modules/@ckeditor/ckeditor5-build-[name]/build/translations/[lang].js`.
-Single language can be loaded directly to your code by importing `'@ckeditor/ckeditor5-build-[name]/build/translations/de.js'`.
+
+Single language can be loaded directly to your code by importing e.g. `'@ckeditor/ckeditor5-build-classic/build/translations/de.js'`.
 
 See {@link builds/guides/integration/installation#npm npm installation guides} for more information.
 
 ### Zip
 
-All additional languages are included in the `.zip` file. You need to include `ckeditor.js` file together with language file:
+All additional languages are included in the `.zip` file. You need to include `ckeditor.js` file together with the chosen language file:
 
-```js
+```html
 <script src="[ckeditor-path]/ckeditor.js"></script>
 <script src="[ckeditor-path]/translations/de.js"></script>
 ```

+ 6 - 8
docs/framework/guides/architecture/core-editor-architecture.md

@@ -9,13 +9,13 @@ The [`@ckeditor/ckeditor5-core`](https://www.npmjs.com/package/@ckeditor/ckedito
 
 ## Editor classes
 
-The {@link module:core/editor/editor~Editor} class represents the base of the editor. It's an entry point of the application, gluing all other components. It provides a couple of properties that you need to know:
+The {@link module:core/editor/editor~Editor} class represents the base of the editor. It is an entry point of the application, gluing all other components. It provides a couple of properties that you need to know:
 
 * {@link module:core/editor/editor~Editor#config} &ndash; The configuration object.
 * {@link module:core/editor/editor~Editor#plugins} and {@link module:core/editor/editor~Editor#commands} &ndash; The collection of loaded plugins and commands.
-* {@link module:core/editor/editor~Editor#model} &ndash; The entry point to editor's abstract data model.
+* {@link module:core/editor/editor~Editor#model} &ndash; The entry point to the {@link framework/guides/architecture/editing-engine#model editor's data model}.
 * {@link module:core/editor/editor~Editor#data} &ndash; The data controller. It controls how data is retrieved from the document and set inside it.
-* {@link module:core/editor/editor~Editor#editing} &ndash; The editing controller. It controls {@link module:engine/model/model~Model#document document} rendering, including selection handling.
+* {@link module:core/editor/editor~Editor#editing} &ndash; The editing controller. It controls how the model is rendered to the user for editing.
 * {@link module:core/editor/editor~Editor#keystrokes} &ndash; The keystroke handler. It allows to bind keystrokes to actions.
 
 Besides that, the editor exposes a few of methods:
@@ -23,13 +23,11 @@ Besides that, the editor exposes a few of methods:
 * {@link module:core/editor/editor~Editor.create `create()`} &ndash; The static `create()` method. Editor constructors are protected and you should create editors using this static method. It allows the initialization process to be asynchronous.
 * {@link module:core/editor/editor~Editor#destroy `destroy()`} &ndash; Destroys the editor.
 * {@link module:core/editor/editor~Editor#execute `execute()`} &ndash; Executes the given command.
+* {@link module:core/editor/utils/dataapimixin~DataApi#setData `setData()`} and {@link module:core/editor/utils/dataapimixin~DataApi#getData `getData()`} &ndash; A way to retrieve data from the editor and set data in the editor. The data format is controlled by the {@link module:engine/controller/datacontroller~DataController#processor data controller's data processor} and it does not need to be a string (it can be e.g. JSON if you implement such a {@link module:engine/dataprocessor/dataprocessor~DataProcessor data processor}). See, for example, how to {@link features/markdown produce Markdown output}.
 
-You can also extend the editor interface using API interfaces:
+For the full list of methods check the {@link api/index API docs} of the specific editor class you use. Specific editor implementations may provide additional methods.
 
-* {@link module:core/editor/utils/elementapimixin~ElementApi} &ndash; A way to retrieve and set data from/to element on which the editor has been initialized.
-* {@link module:core/editor/utils/dataapimixin~DataApi} &ndash; A way to retrieve data from the editor and set data in the editor. The data format is controlled by the {@link module:engine/controller/datacontroller~DataController#processor data controller's data processor} and it does not need to be a string (it can be e.g. JSON if you implement such a {@link module:engine/dataprocessor/dataprocessor~DataProcessor data processor}). See, for example, how to {@link features/markdown produce Markdown output}.
-
-The editor class is a base to implement your own editors. CKEditor 5 Framework comes with a few editor types (for example, {@link module:editor-classic/classiceditor~ClassicEditor classic}, {@link module:editor-inline/inlineeditor~InlineEditor inline} and {@link module:editor-balloon/ballooneditor~BalloonEditor balloon}) but you can freely implement editors which work and look completely different. The only requirement is that you implement the {@link module:core/editor/editor~Editor} interface.
+The {@link module:core/editor/editor~Editor `Editor`} class is a base to implement your own editors. CKEditor 5 Framework comes with a few editor types (for example, {@link module:editor-classic/classiceditor~ClassicEditor classic}, {@link module:editor-inline/inlineeditor~InlineEditor inline} and {@link module:editor-balloon/ballooneditor~BalloonEditor balloon}) but you can freely implement editors which work and look completely different. The only requirement is that you implement the {@link module:core/editor/editor~Editor} interface.
 
 ## Plugins
 

+ 139 - 13
docs/framework/guides/architecture/editing-engine.md

@@ -21,21 +21,55 @@ Let's now talk about each layer separately.
 
 ## Model
 
-The model is implemented by a DOM-like tree structure of {@link module:engine/model/element~Element elements} and {@link module:engine/model/text~Text text nodes}. Like in the DOM, its central point is a {@link module:engine/model/document~Document document} which contains {@link module:engine/model/document~Document#roots root elements} (the model, as well as the view, may have multiple roots). The document also holds its {@link module:engine/model/documentselection~DocumentSelection selection}, {@link module:engine/model/history~History history of changes} and {@link module:engine/model/schema~Schema schema}.
+The model is implemented by a DOM-like tree structure of {@link module:engine/model/element~Element elements} and {@link module:engine/model/text~Text text nodes}. Unlike in the DOM, in the model, both, elements and text nodes can have attributes.
 
-All changes made to the document structure are done by applying {@link module:engine/model/operation/operation~Operation operations}. The concept of operations comes from [Operational Transformation](https://en.wikipedia.org/wiki/Operational_transformation) (in short: OT), a technology enabling collaboration functionality. Since OT requires that a system is able to transform every operation by every other one (to figure out the result of concurrently applied operations), the set of operations needs to be small. CKEditor 5 features a non-linear model (normally, OT implementations use flat, array-like models while CKEditor 5 uses a tree structure), hence the set of potential semantic changes is more complex. To handle that, the editing engine implements a small set of operations (six to be precise) and a bigger set of {@link module:engine/model/delta/delta~Delta "deltas"} &mdash; groups of operations with additional semantics attached (there are eleven deltas and the number will grow). Finally, deltas are grouped in {@link module:engine/model/batch~Batch batches}. A batch can be understood as a single undo step.
+Like in the DOM, the model's structure is contained within a {@link module:engine/model/document~Document document} which contains {@link module:engine/model/document~Document#roots root elements} (the model, as well as the view, may have multiple roots). The document also holds its {@link module:engine/model/documentselection~DocumentSelection selection} and the {@link module:engine/model/history~History history of its changes}.
 
-<info-box>
-	The technology implemented by CKEditor 5 is experimental. The subject of applying Operational Transformation to tree structures is not yet well researched and, in early 2015 when we started designing and implementing our own system, we were aware of just one existing and proven implementation (of which there was little information).
+Finally, the document, its {@link module:engine/model/schema~Schema schema} and {@link module:engine/model/markercollection~MarkerCollection document markers} are properties of the {@link module:engine/model/model~Model}. Instance of the `Model` class is available in the {@link module:core/editor/editor~Editor#model `editor.model`} property. The model, besides holding the properties described above, provides also the API for changing the document and its markers.
+
+```js
+editor.model;                       // -> The data model
+editor.model.document;              // -> The document
+editor.model.document.getRoot();    // -> Document's root
+editor.model.document.selection;    // -> Document's selection
+editor.model.schema;                // -> Model's schema
+```
 
-	During the last 3 years we changed our approach and reworked the implementation multiple times. In fact, we are still learning about new types of issues and constantly align and improve the engine. One of the most important things that we learned was that implementing OT is just a part of the job on your way to real-time collaborative editing. We needed to create additional mechanisms and change the whole architecture to enable concurrent editing by multiple users with features like undo and ability to display selections of other users.
+### Changing the model
 
-	As a result of all this, the API and some important concepts are constantly changing. We have the implementation well tested already, but the engine still requires [a lot of cleaning and some implementation tweaks](https://github.com/ckeditor/ckeditor5-engine/issues/1008).
+All changes in the document structure, of the document's selection and even creation of elements, can only be done by using the {@link module:engine/model/writer~Writer model writer}. Its instance is available in {@link module:engine/model/model~Model#change `change()`} and {@link module:engine/model/model~Model#enqueueChange `enqueueChange()`} blocks.
 
-	This means that information from this guide may be a bit confusing when confronted with the existing APIs. For instance, you may find that [model elements and text nodes can be modified directly](https://github.com/ckeditor/ckeditor5-engine/issues/858) (without applying operations). Please keep that in mind, and when in doubt, [report issues](https://github.com/ckeditor/ckeditor5-engine/issues/new).
-</info-box>
+```js
+// Inserts text "foo" at the selection position.
+editor.model.change( writer => {
+	writer.insertText( 'foo', editor.model.document.selection.getFirstPosition() );
+} );
+
+// Apply bold to the entire selection.
+editor.model.change( writer => {
+	for ( const range of editor.model.document.selection.getRanges() ) {
+		writer.setAttribute( 'bold', true, range );
+	}
+} );
+```
+
+All changes done within a single `change()` block are combined into one undo step (they are added to a single {@link module:engine/model/batch~Batch batch}). When nesting `change()` blocks, all changes are added to the outermost `change()` block's batch. For example, the below code will create a single undo step:
 
-As mentioned earlier, going into details would make an awfully long article, so only a few more notable facts will be explained here.
+```js
+editor.model.change( writer => {
+	writer.insertText( 'foo', paragraph, 'end' ); // foo.
+
+	editor.model.change( writer => {
+		writer.insertText( 'bar', paragraph, 'end' ); // foobar.
+	} );
+
+	writer.insertText( 'bom', paragraph, 'end' ); // foobarbom.
+} );
+```
+
+<info-box>
+	All changes made to the document structure are done by applying {@link module:engine/model/operation/operation~Operation operations}. The concept of operations comes from [Operational Transformation](https://en.wikipedia.org/wiki/Operational_transformation) (in short: OT), a technology enabling collaboration functionality. Since OT requires that a system is able to transform every operation by every other one (to figure out the result of concurrently applied operations), the set of operations needs to be small. CKEditor 5 features a non-linear model (normally, OT implementations use flat, array-like models while CKEditor 5 uses a tree structure), hence the set of potential semantic changes is more complex. To handle that, the editing engine implements a small set of operations and a bigger set of {@link module:engine/model/delta/delta~Delta "deltas"} &mdash; groups of operations with additional semantics attached. Finally, deltas are grouped in {@link module:engine/model/batch~Batch batches}. A batch can be understood as a single undo step.
+</info-box>
 
 ### Text attributes
 
@@ -78,7 +112,7 @@ OK, but how to let CKEditor 5 know that I want the selection to "be bold" in the
 
 To handle that, selection also {@link module:engine/model/selection~Selection#setAttribute has attributes}. If the selection is placed in `"Foo ^bar"` and it has the attribute `bold=true`, you know that the user will type bold text.
 
-### Positions
+### Indexes and offsets
 
 However, it has just been said that inside `<paragraph>` there are two text nodes: `"Foo "` and `"bar"`. If you know how [native DOM Ranges](https://developer.mozilla.org/en-US/docs/Web/API/Range) work you might thus ask: "But if the selection is at the boundary of two text nodes, is it anchored in the left one, the right one, or in the containing element?"
 
@@ -105,15 +139,107 @@ On the other hand, offset `x` in `<paragraph>` translates to:
 | `4`    | `<paragraph>Foo ^<image></image>bar</paragraph>` | `<image>` |
 | `6`    | `<paragraph>Foo <image></image>b^ar</paragraph>` | `"bar"`   |
 
-The engine also defines three main classes which operate on offsets:
+### Positions, ranges and selections
+
+The engine also defines three levels of classes which operate on offsets:
 
 * A {@link module:engine/model/position~Position} instance contains an {@link module:engine/model/position~Position#path array of offsets} (which is called a "path"). See the examples in {@link module:engine/model/position~Position#path `Position#path` API documentation} to better understand how paths work.
 * {@link module:engine/model/range~Range} contains two positions: {@link module:engine/model/range~Range#start start} and {@link module:engine/model/range~Range#end end} ones.
-* Finally, there is {@link module:engine/model/selection~Selection} which contains one or more ranges and attributes.
+* Finally, there is a {@link module:engine/model/selection~Selection} which contains one or more ranges and attributes. You can make as many instances of it as you needed and you can freely modify it whenever you want.  Additionally, there is a single {@link module:engine/model/documentselection~DocumentSelection}. It represents the document's selection and can only be changed through the {@link module:engine/model/writer~Writer model writer}. It is automatically updated when the document's structure is changed.
+
+### Markers
+
+Markers are a special type of ranges.
+
+* They are managed by {@link module:engine/model/markercollection~MarkerCollection}.
+* They can only be created and changed through the {@link module:engine/model/writer~Writer model writer}.
+* They cane be synchronized over the network with other collaborating clients.
+* They are automatically updated when the document's structure is changed.
+* They can be converted to attributes or elements in the [view](#view).
+
+This makes them ideal for storing and maintaining additional data in the model – such as comments, selections of other users, etc.
+
+### Schema
+
+The {@link module:engine/model/schema~Schema model's schema} defines several aspects of how the model should look:
+
+* where a node is allowed or disallowed (e.g. `paragraph` is allowed in `$root`, but not in `heading1`),
+* what attributes are allowed on a certain node (e.g. `image` can have `src` and `alt` attributes),
+* additional semantics of model nodes (e.g. `image` is of the "object" type and paragraph of the "block" type).
+
+This information is then used by features and the engine to make decisions how to process the model. For instance, the information from the schema will affect:
+
+* what happens with a pasted content - what is filtered out (note: in case of pasting the other important mechanism is the conversion – HTML elements and attributes which are not upcasted by any of the registered converters are filtered out before they even become model nodes, so the schema is not applied to them; we'll cover conversion later in this guide),
+* to which elements the heading feature can be applied (which blocks can be turned to headings and which elements are blocks in the first place),
+* which elements can be wrapped with a block quote,
+* whether the bold button is enabled when the selection is in a heading (and whether text in this heading can be bolded),
+* where the selection can be placed (which is – only in text nodes and on object elements),
+* etc.
+
+The schema is, by default, configured by editor plugins. It is recommended that every editor feature come with rules which enable and preconfigure it in the editor. This will make sure that the plugin's user can enable it without worrying to re-configure her/his schema.
+
+<info-box>
+	Currently, there is [no straightforward way to override the schema](https://github.com/ckeditor/ckeditor5-engine/issues/1367) preconfigured by features. If you want to override the default settings when initializing the editor, the best solution is to replace `editor.model.schema` with a new instance of. This, however, requires rebuilding the editor.
+</info-box>
+
+The instance of the schema is available in {@link module:engine/model/model~Model#schema `editor.model.schema`}. Read an extensive guide about using the schema API in {@link module:engine/model/schema~Schema API docs for the `Schema` class}.
 
 ## View
 
-## Controller
+Let's again take a look at the editing engine's architecture:
+
+[{@img assets/img/framework-architecture-engine-diagram.png Diagram of the engine's MVC architecture.}](%BASE_PATH%/assets/img/framework-architecture-engine-diagram.png)
+
+So far, we talked about the topmost layer of this diagram – the model. The role of the model layer is to create an abstraction over the data. Its format was designed to allow storing and modifying the data in the most convenient way, while enabling implementation of complex features. Most features operate (read from it and change it) on the model.
+
+The view, on the other hand, is an abstract representation of the DOM structure which should be presented to the user (for editing) and which should (in most cases) represent the editor's input/output (i.e. data returned by `editor.getData()`, data set by `editor.setData()`, pasted content, etc.).
+
+What this means is that:
+
+* The view is yet another custom structure.
+* It resembles the DOM. While the model's tree structure only slightly resembled the DOM (e.g. by introducing text attributes), the view is much closer to the DOM. In other words, it is a **virtual DOM**.
+* There are two "pipelines" – the **editing pipeline** (also called the "editing view") and the **data pipeline** ("the data view"). Treat them as two separate views of one model. The editing pipeline renders and handles the DOM which the user sees and can edit. The data pipeline is used when you call `editor.getData()`, `editor.setData()` or paste content into the editor.
+
+The fact that there are two views is visible in the API:
+
+```js
+editor.editing;                 // The editing pipeline (EditingController).
+editor.editing.view;            // Editing view's controller.
+editor.editing.view.document;   // Editing view's document.
+editor.data;                    // The data pipeline (DataController).
+```
+
+<info-box>
+	Technically, the data pipeline does not have a document and a view controller. It operates on detached view structures, created for the purposes of processing a data.
+
+	It is much simpler than the editing pipeline and in the following part of this section we will be talking about the editing view.
+
+	Check out the {@link module:engine/controller/editingcontroller~EditingController}'s and {@link module:engine/controller/datacontroller~DataController}'s API.
+</info-box>
+
+### Changing the view
+
+Do not change the view manually, unless you really know what you do. If the view needs to be changed, in most cases, it means that the model should be changed first. Then, the changes you apply to the model are converted ([conversion](#conversion) is covered below) to the view by specific converters.
+
+The view may need to be changed manually if the cause of such a change is not represented in the model. For example, the model does not store information about the focus, which is a {@link module:engine/view/document~Document#isFocused property of the view}. When the focus changes, and you want to represent that in some element's class, you need to change that class manually.
+
+For that, just like in the model, you should use the `change()` block (of the view) in which you will have access to the view writer.
+
+```js
+editor.data.view.change( writer => {
+	writer.insert( position1, writer.createText( 'foo' ) );
+} );
+```
+
+### Element types
+
+### Positions
+
+### Observers
+
+## Conversion
+
+TODO: upcasting, downcasting, why and how.
 
 ## Read next
 

+ 1 - 0
docs/framework/guides/architecture/intro.md

@@ -1,6 +1,7 @@
 ---
 category: framework-architecture
 order: 10
+toc: false
 ---
 
 # Introduction

+ 61 - 28
docs/framework/guides/quick-start.md

@@ -14,7 +14,11 @@ The framework is made of several [npm packages](https://npmjs.com). To install i
 * [Node.js](https://nodejs.org/en/) >= 6.0.0
 * npm 4.x (**note:** using npm 5 [is not recommended](https://github.com/npm/npm/issues/16991))
 
-Besides Node.js and npm you also need [webpack](https://webpack.js.org) (>=2.0.0) with a few additional packages to use the framework. They are needed to bundle the source code. Read more about building CKEditor 5 in the {@link builds/guides/integration/advanced-setup CKEditor 5 Builds Advanced setup} guide.
+Besides Node.js and npm you also need [webpack@3.x](https://webpack.js.org) with a few additional packages to use the framework. They are needed to bundle the source code. Read more about building CKEditor 5 in the {@link builds/guides/integration/advanced-setup CKEditor 5 Builds Advanced setup} guide.
+
+<info-box warning>
+	Unfortunately, at the moment of writing this note, [webpack@4.x causes issues](https://github.com/ckeditor/ckeditor5-dev/issues/371).
+</info-box>
 
 <!-- TODO replace the link above when the Framework will get its own building guide. -->
 
@@ -29,7 +33,7 @@ npm install --save \
 	postcss-loader \
 	raw-loader \
 	style-loader \
-	webpack
+	webpack@^3.11.0
 ```
 
 The minimal webpack configuration needed to enable building CKEditor 5 is:
@@ -176,11 +180,19 @@ bundle.js.map   2.2 MB       0  [emitted]         main
 Finally, it is time to create an HTML page:
 
 ```html
-<div id="editor">
-	<p>Editor content goes here.</p>
-</div>
-
-<script src="dist/bundle.js"></script>
+<!DOCTYPE html>
+<html>
+	<head>
+		<meta charset="utf-8">
+		<title>CKEditor 5 Framework – Quick start</title>
+	</head>
+
+	<div id="editor">
+		<p>Editor content goes here.</p>
+	</div>
+
+	<script src="dist/bundle.js"></script>
+</html>
 ```
 
 Open this page in your browser and you should see the editor up and running. Make sure to check the browser console in case anything seems wrong.
@@ -201,13 +213,18 @@ Start from installing necessary dependencies:
 
 * The [`@ckeditor/ckeditor5-image`](https://www.npmjs.com/package/@ckeditor/ckeditor5-image) package that contains the image feature (on which the plugin will rely).
 * The [`@ckeditor/ckeditor5-core`](https://www.npmjs.com/package/@ckeditor/ckeditor5-core) package which contains the {@link module:core/plugin~Plugin} and {@link module:core/command~Command} classes.
-* The [`@ckeditor/ckeditor5-engine`](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine) package which contains the editing engine.
 * The [`@ckeditor/ckeditor5-ui`](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui) package which contains the UI library and framework.
 
 ```bash
-npm install --save @ckeditor/ckeditor5-image @ckeditor/ckeditor5-core @ckeditor/ckeditor5-engine
+npm install --save @ckeditor/ckeditor5-image \
+	@ckeditor/ckeditor5-core \
+	@ckeditor/ckeditor5-ui
 ```
 
+<info-box>
+	Most of the time, you will also want to install the [`@ckeditor/ckeditor5-engine`](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine) package (it contains the {@link framework/guides/architecture/editing-engine editing engine}). It was omitted in this guide because it is unnecessary for a simple plugin like this one.
+</info-box>
+
 Now, open the `app.js` file and start adding code there. Usually, when implementing more complex features you will want to split the code into multiple files (modules). However, to make this guide simpler the entire code will be kept in `app.js`.
 
 First thing to do will be to load the core of the image feature:
@@ -234,7 +251,7 @@ Save the file and run webpack. Refresh the page in your browser (**remember abou
 	<p>Simple image:</p>
 
 	<figure class="image">
-		<img src="https://via.placeholder.com/1000x300/02c7cd/fff?text=Placeholder image" alt="CKEditor 5 rocks!">
+		<img src="https://via.placeholder.com/1000x300/02c7cd/fff?text=Placeholder%20image" alt="CKEditor 5 rocks!">
 	</figure>
 </div>
 ```
@@ -319,22 +336,37 @@ Rebuild the application and refresh the page. You should see a new button in the
 ### Step 4. Inserting a new image
 
 ```js
-import ModelElement from '@ckeditor/ckeditor5-engine/src/model/element';
+class InsertImage extends Plugin {
+	init() {
+		const editor = this.editor;
 
-// ...
+		editor.ui.componentFactory.add( 'insertImage', locale => {
+			const view = new ButtonView( locale );
 
-view.on( 'execute', () => {
-	const imageUrl = prompt( 'Image URL' );
+			view.set( {
+				label: 'Insert image',
+				icon: imageIcon,
+				tooltip: true
+			} );
 
-	editor.document.enqueueChanges( () => {
-		const imageElement = new ModelElement( 'image', {
-			src: imageUrl
-		} );
+			// Callback executed once the image is clicked.
+			view.on( 'execute', () => {
+				const imageUrl = prompt( 'Image URL' );
 
-		// Insert the image in the current selection location.
-		editor.data.insertContent( imageElement, editor.document.selection );
-	} );
-} );
+				editor.model.change( writer => {
+					const imageElement = writer.createElement( 'image', {
+						src: imageUrl
+					} );
+
+					// Insert the image in the current selection location.
+					editor.model.insertContent( imageElement, editor.model.document.selection );
+				} );
+			} );
+
+			return view;
+		} );
+	}
+}
 ```
 
 If you refresh the page, you should now be able to insert new images into the content:
@@ -388,11 +420,10 @@ import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
 import Image from '@ckeditor/ckeditor5-image/src/image';
 import ImageCaption from '@ckeditor/ckeditor5-image/src/imagecaption';
 
-import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
+import Plugin from '@ckeditor/ckeditor5-core/src/plugin';;
 import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
-import ModelElement from '@ckeditor/ckeditor5-engine/src/model/element';
 
-import imageIcon from '@ckeditor/ckeditor5-core/theme/icons/image.svg';
+import imageIcon from '@ckeditor/ckeditor5-core/theme/icons/image.svg'
 
 class InsertImage extends Plugin {
 	init() {
@@ -407,15 +438,17 @@ class InsertImage extends Plugin {
 				tooltip: true
 			} );
 
+			// Callback executed once the image is clicked.
 			view.on( 'execute', () => {
 				const imageUrl = prompt( 'Image URL' );
 
-				editor.document.enqueueChanges( () => {
-					const imageElement = new ModelElement( 'image', {
+				editor.model.change( writer => {
+					const imageElement = writer.createElement( 'image', {
 						src: imageUrl
 					} );
 
-					editor.data.insertContent( imageElement, editor.document.selection );
+					// Insert the image in the current selection location.
+					editor.model.insertContent( imageElement, editor.model.document.selection );
 				} );
 			} );
 

+ 1 - 0
docs/umberto.json

@@ -2,6 +2,7 @@
 	"name": "CKEditor 5",
 	"slug": "ckeditor5",
 	"hexo-config": "docs/hexo-custom-config.json",
+	"extraStyles": "assets/styles.css",
 	"path": "docs",
 	"observablesdocs": "module:utils/observablemixin~ObservableMixin",
 	"scripts": {

+ 37 - 37
package.json

@@ -1,6 +1,6 @@
 {
   "name": "ckeditor5",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-beta.1",
   "description": "The development environment of CKEditor 5.",
   "keywords": [
     "CKEditor",
@@ -13,41 +13,41 @@
     "editing framework"
   ],
   "dependencies": {
-    "@ckeditor/ckeditor5-adapter-ckfinder": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-alignment": "^0.0.1",
-    "@ckeditor/ckeditor5-autoformat": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-basic-styles": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-block-quote": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-build-balloon": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-build-classic": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-build-decoupled-document": "^0.0.1",
-    "@ckeditor/ckeditor5-build-inline": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-clipboard": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-cloudservices": "^1.0.0-alpha.1",
-    "@ckeditor/ckeditor5-core": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-easy-image": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-editor-balloon": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-editor-classic": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-editor-decoupled": "^0.0.1",
-    "@ckeditor/ckeditor5-editor-inline": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-engine": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-enter": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-essentials": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-font": "^0.0.1",
-    "@ckeditor/ckeditor5-heading": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-highlight": "^0.0.1",
-    "@ckeditor/ckeditor5-image": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-link": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-list": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-markdown-gfm": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-paragraph": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-theme-lark": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-typing": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-ui": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-undo": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-upload": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-utils": "^1.0.0-alpha.2",
-    "@ckeditor/ckeditor5-widget": "^1.0.0-alpha.2"
+    "@ckeditor/ckeditor5-adapter-ckfinder": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-alignment": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-autoformat": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-basic-styles": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-block-quote": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-build-balloon": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-build-classic": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-build-decoupled-document": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-build-inline": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-clipboard": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-cloudservices": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-core": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-easy-image": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-editor-balloon": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-editor-classic": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-editor-decoupled": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-editor-inline": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-engine": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-enter": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-essentials": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-font": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-heading": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-highlight": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-image": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-link": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-list": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-markdown-gfm": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-paragraph": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-theme-lark": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-typing": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-ui": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-undo": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-upload": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-utils": "^1.0.0-beta.1",
+    "@ckeditor/ckeditor5-widget": "^1.0.0-beta.1"
   },
   "devDependencies": {
     "@ckeditor/ckeditor5-dev-docs": "^8.0.0",
@@ -68,7 +68,7 @@
     "postcss-loader": "^2.0.10",
     "raw-loader": "^0.5.1",
     "style-loader": "^0.19.1",
-    "umberto": "^0.3.48",
+    "umberto": "^0.4.0",
     "webpack": "^3.10.0",
     "webpack-sources": "1.0.1"
   },