Parcourir la source

Merge branch 'docs'

Docs: Ported first batch of guides.
Piotrek Koszuliński il y a 8 ans
Parent
commit
8284b6286f

+ 147 - 0
docs/builds/guides/development/custom-builds.md

@@ -0,0 +1,147 @@
+---
+# Scope:
+# * Introduction on custom builds and why one would create them.
+# * Simple step by step on creating a custom build.
+
+title: Custom builds
+category: builds-development
+order: 10
+---
+
+# Creating custom builds
+
+In a few words, a build is a simple [npm](https://www.npmjs.com) package (usually developed in a Git repository) with a predefined set of dependencies. Out of this repository, distribution files can be generated through a build process.
+
+These are some of the reasons for creating custom builds:
+
+* Adding features which are not included in the existing builds, either from third party or custom developed.
+* Removing unnecessary features present in a build.
+* Change the {@link TODO builds/guides/integration/basic-api.html#Creators editor creator}.
+* Changing the editor theme.
+* Changing the localization language of the editor.
+* Enabling bug fixes which are not part of any public release still.
+
+## Forking existing build
+
+[Fork](https://help.github.com/articles/fork-a-repo/) one of the official builds (it’ll serve as the starting point for your custom one) and then clone your fork:
+
+```
+git clone https://github.com/<your-username>/ckeditor5-build-classic.git
+```
+
+You may optionally add the original build repository to your git remotes, to make updating easier:
+
+```
+git remote add upstream https://github.com/ckeditor/ckeditor5-build-classic.git
+```
+
+<side-box tip>
+	If you don't want to fork the official build, you can just clone it. However, you won't be able to commit and push your customizations back to [GitHub](https://github.com).
+</side-box>
+
+## Build's anatomy
+
+Every build contains the following files:
+
+* `package.json` – npm package's definition (it specifies the package name, version, dependencies, license, etc.).
+* `build-config.js` – configuration of this particular CKEditor 5 build.
+* `ckeditor.js` – bundler's "entry file". A CommonJS module which tells the bundler (like [Webpack](https://webpack.js.org)) which CKEditor modules should be included in the bundle and what should that bundle export). By default, it's created based on the build configuration but you may also modify it manually.
+* `build/*` – directory with ready-to-use bundles. There are two bundles:
+	* the most optimized, ES6 one in `build/ckeditor.js`,
+	* and ES5 one in `build/ckeditor.compat.js`.
+
+## Customizing a build
+
+In order to customize a build you need to:
+
+* install missing dependencies,
+* update the `build-config.js`,
+* updating builds (which includes updating `ckeditor.js` and editor bundles in `build/*`).
+
+### Installing dependencies
+
+The easiest way to install missing dependencies is by typing:
+
+```
+npm install --save <package-name>
+```
+
+This will install the package and add it to `package.json`. You can also edit `package.json` manually.
+
+<side-box tip>
+	Due to a non-deterministic way how npm installs packages, it's recommended to run `rm -rf node_modules && npm install` when in doubt. This will prevent some packages to get installed more than once in `node_modules/` what might lead to broken builds.
+
+	You can also give [yarn](https://yarnpkg.com/lang/en/) a try.
+<side-box>
+
+### Updating build configuration
+
+If you added or removed dependencies, you will also need to modify the `build-config.js` file. Based on it the bundler entry file (`ckeditor.js`) will be created. You can also opt-out from automatically creating the entry file and modify `ckeditor.js` manually which can be useful in some non-standard cases.
+
+Either way, every plugin which you want to include in the bundle should be included at this stage. You can also change the editor creator and specify editor's default config. For instance, your build config can look like this:
+
+```
+'use strict';
+
+module.exports = {
+	editor: '@ckeditor/ckeditor5-editor-classic/src/classic',
+	moduleName: 'ClassicEditor',
+	plugins: [
+		'@ckeditor/ckeditor5-presets/src/essentials',
+
+		'@ckeditor/ckeditor5-autoformat/src/autoformat',
+		'@ckeditor/ckeditor5-basic-styles/src/bold',
+		'@ckeditor/ckeditor5-basic-styles/src/italic',
+		'@ckeditor/ckeditor5-heading/src/heading',
+		'@ckeditor/ckeditor5-link/src/link',
+		'@ckeditor/ckeditor5-list/src/list',
+		'@ckeditor/ckeditor5-paragraph/src/paragraph',
+
+		'ckeditor5-custom-package/src/customplugin',
+		'../relative/path/to/some/othercustomplugin'
+	],
+	config: {
+		toolbar: [ 'headings', 'bold', 'italic', 'custombutton' ]
+	}
+};
+```
+
+### Rebuilding the bundle
+
+After you changed the build configuration or updated some dependencies, it's time to rebuild the bundle. This will run a bundler (Webpack) with a proper configuration (see `webpack.config.js` and `webpack.compat.config.js`).
+
+If you wish to create the bundles based on the build configuration (`build-config.js`) run:
+
+```
+npm run build
+```
+
+This command will update the entry file (`ckeditor.js`) and create two bundles – `build/ckeditor.js` and `build/ckeditor.compat.js`.
+
+If you want to use to skip updating the entry file (in case you modified it manually) run:
+
+```
+npm run build-ckeditor
+npm run build-ckeditor-compat
+```
+
+## Updating build
+
+You may decide to update your build at any time. Being it a fork of an official build, it is just a matter of merging changes that happened meanwhile in that build, by using git features:
+
+```
+git fetch upstream
+git merge upstream/master
+```
+
+You should handle eventual conflicts and verify the merged changes. After that, just follow the previous instructions for creating your build and test it.
+
+<side-box tip>
+	It's recommended to run `rm -rf node_modules && npm install` after you fetched changes from the upstream or updated versions of dependencies in `package.json` manually. This will prevent npm from installing packages more than once which may lead to broken builds.
+</side-box>
+
+## Publishing your builds
+
+If you think that your custom builds can be useful to others, it is a great idea to publish them in GitHub and npm. When doing so, just be sure to find nice names for them and to fit them in the `ckeditor5-build-(the name)` pattern, making it easy to find them to everyone. To avoid conflicts with other existing builds you can use [scoped packages](https://docs.npmjs.com/misc/scope).
+
+After your build is out, [ping us on Twitter](https://twitter.com/ckeditor)!

+ 109 - 0
docs/builds/guides/integration/basic-api.md

@@ -0,0 +1,109 @@
+---
+# Scope:
+# * Guide developers through the basic API to achieve their very first results with CKEditor.
+
+title: Basic API
+category: builds-integration
+order: 20
+---
+
+## Creators
+
+Each CKEditor 5 build provides a class that handles the creation of editor instances inside a page. For this reason they’re called “creators”. Every creator comes with a static `create()` method.
+
+The following are creator class names for each build:
+
+* Classic Editor: {@link module:editor-classic/classiceditor~ClassicEditor}
+* Inline Editor: {@link module:editor-inline/inlineeditor~InlineEditor}
+* Medium-like Editor: {@link module:editor-medium-like/mediumlikeeditor~MediumLikeEditor}
+
+Most of the examples in the documentation use the `ClassicEditor` class, but things should work in similar way with other creator classes.
+
+Because builds are distributed as [UMD modules](https://github.com/umdjs/umd), these classes can be retrieved:
+
+* by [CommonJS](http://wiki.commonjs.org/wiki/CommonJS) compatible loader (e.g. [Webpack](https://webpack.js.org) or [Browserify](http://browserify.org/)),
+* by [RequireJS](http://requirejs.org/) (or any other AMD library),
+* from the global namespace if none of the above loaders is not available.
+
+For example:
+
+```js
+// In CommonJS environment.
+const ClassicEditor = require( '@ckeditor/ckeditor5-build-classic/build/ckeditor.js' );
+ClassicEditor.create; // [Function]
+
+// If AMD is present, you can do this.
+require( '/(ckeditor path)/build/ckeditor.js', ClassicEditor => {
+	ClassicEditor.create; // [Function]
+} );
+
+// As a global.
+ClassicEditor.create; // [Function]
+```
+
+Having the above in mind, depending on which build you’re using, creating an editor in the page is a breeze:
+
+In the HTML:
+
+```html
+<textarea id="text-editor">
+	&lt;p&gt;Here goes the initial contents of the editor.&lt;/p&gt;
+</textarea>
+```
+
+In the script:
+
+```js
+ClassicEditor.create( document.querySelector( '#text-editor' ) )
+	.then( editor => {
+		console.log( editor );
+	} )
+	.catch( error => {
+		console.error( error );
+	} );
+```
+
+In the above case, the `<textarea>` element is hidden and replaced with an editor. The `<textarea>` data is used to initialize the editor contents. A `<div>` element could have been used in the same fashion.
+
+<side-box info>
+	Every creator may accept different parameters and handle initialization differently. For instance, the classic editor will replace a given element with an editor, while the inline editor will use the given element to initialize the editor on it. See each editor's documentation to learn the details.
+
+	The interface of the editor class isn't enforced either. Since different implementations of editors may vary heavily in terms of functionality, the editor class implementers have full freedom regarding the API. Therefore, the examples in this guide may not work with some editor classes.
+</side-box>
+
+## Interacting with the editor
+
+Once the editor is created, it is possible to interact with it through its API. The `editor` variable, from the above examples, should enable that.
+
+### Setting the editor data
+
+To replace the editor contents with new data, just use the `setData` method:
+
+```js
+editor.setData( '<p>Some text.</p>' );
+```
+
+### Getting the editor data
+
+If the editor contents need to be retrieved for any reason, like for the scope of sending it to the server through an Ajax call, simply use the `getData` method:
+
+```js
+const data = editor.getData();
+```
+
+### Destroying the editor
+
+In modern applications, it is common to create and remove elements from the page interactively through JavaScript. CKEditor instances should be destroyed in such cases by using the `destroy()` method:
+
+```js
+editor.destroy()
+	.catch( error => {
+		console.log( error );
+	} );
+```
+
+Once destroyed, resources used by the editor instance are released and the original element used to create the editor is automatically displayed and updated to reflect the final editor data.
+
+## What’s more?
+
+CKEditor offers a rich API to interact with editors. Check out the {@link TODO API documentation} for more.

+ 87 - 0
docs/builds/guides/integration/configuration.md

@@ -0,0 +1,87 @@
+---
+# Scope:
+# * Introduction on how to set configurations.
+# * Introduction on the top/must-know configurations.
+# * Point where to find the list of configuration options.
+
+title: Configuration
+category: builds-integration
+order: 30
+---
+
+When creating an editor in your page, it is possible to setup configurations that changes many of its aspects. For example:
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#text-editor' ), {
+		toolbar: [ 'bold', 'link' ],
+		removePlugins: [ 'ImageToolbar', 'ImageStyle' ]
+	} )
+	.catch( error => {
+		console.log( error );
+	} );
+```
+
+As you can see, configurations are set by a simple JavaScript object passed to the editor creator class. It works in the same fashion when the create method is used instead.
+
+## Enabling features
+
+Builds come with all features included in the distribution package enabled by default. They’re defined as plugins for CKEditor.
+
+In some cases, you may need to have different editor setups in your application, all based on the same build. For that purpose, you need to control the plugins available in an editor at runtime. The following are a few examples:
+
+```js
+// Remove a few plugins from the default setup.
+ClassicEditor
+	.create( document.querySelector( '#text-editor' ), {
+		removePlugins: [ 'Heading', 'Link' ]
+	} )
+	.catch( error => {
+		console.log( error );
+	} );
+```
+
+```js
+// Define the full list of plugins to enable.
+ClassicEditor
+	.create( document.querySelector( '#text-editor' ), {
+		plugins: [ 'Paragraph', 'Heading', 'Bold', 'Link' ]
+	} )
+	.catch( error => {
+		console.log( error );
+	} );
+```
+
+<side-box tip>
+	If a build contains too many or too few features, the best approach is creating a custom build instead of simply using configurations.
+</side-box>
+
+### List of plugins
+
+Each build has a number of plugins available. You can easily list all plugins available in your build:
+
+```js
+ClassicEditor.build.plugins.map( plugin => plugin.pluginName );
+```
+
+## Toolbar setup
+
+On builds that contain toolbars, an optimal default configuration is defined for it. You may need a different toolbar arrangement though and this can be achieved through configuration.
+
+Each creator may have a different toolbar configuration scheme, so it is recommended to check the creator API documentation. In any case, the following example may give you a general idea of it:
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#text-editor' ), {
+		toolbar: [ 'bold', 'italic', 'link' ]
+	} )
+	.catch( error => {
+		console.log( error );
+	} );
+```
+
+<side-box tip>
+	The above is a strict UI related configuration. Removing a toolbar item don’t remove the feature from the editor internals. If you goal with the toolbar configuration is removing features, the right solution is removing their relative plugins. Check [Enabling features](#Enabling-features) above for more information.
+</side-box>
+
+<!-- TODO Add section about other configuration options. -->

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

@@ -0,0 +1,65 @@
+---
+# Scope:
+# - Guidance on all possible installation options.
+
+title: Installation
+category: builds-integration
+order: 10
+---
+
+## Download options
+
+The goal of installing any of the CKEditor 5 builds is enabling you to using its API when integrating it inside your application. For that purpose, several options are available:
+
+* [Zip download](#Zip-download)
+* [CDN](#CDN)
+* [npm](#npm)
+
+Each of the builds have independent release packages. Before starting, you must define which one you’re interested on. Check the Overview page for the list of available builds.
+
+### Zip download
+
+Go to http://ckeditor.com/ckeditor5-builds/download and download the build your prefered build. For example, you may download the `ckeditor5-build.classic-1.0.0.zip` file for the Classic Editor build.
+
+Extract the above zip file into a dedicated directory inside your website/application.
+
+The main entry point script will be then available are `<your-path>/ckeditor/build/ckeditor.js`.
+
+### CDN
+
+Builds can be loaded inside pages directly from our CDN, which is optimized for worldwide super-fast speed download.
+
+Check out the {@link TODO CKEditor 5 Builds CDN website} for a list of URL entry points for the builds API.
+
+### npm
+
+All builds are released on npm. The following search shows all build packages available there: https://www.npmjs.com/search?q=%40ckeditor%2Fckeditor5-build
+
+Installing a build with npm is as simple as calling the following inside your website/application:
+
+```
+npm install --save @ckeditor/ckeditor5-build-classic
+```
+
+The script entry point for the build class will be found then at `node_modules/ckeditor5-build-classic/build/ckeditor.js`.
+
+## Included Files
+
+The following are the main files available in all build distributions:
+
+* `build/ckeditor.js`: the main UMD distribution script, containing the editor core and all plugins. Compatible with ECMAScript 6 enabled browsers. A smaller download.
+* `build/ckeditor.compat.js`: the same as the above, for browsers not compatible with ES6.
+* `ckeditor.js`: the source entry point of the build. Can be used for complex bundling and development.
+
+## Loading the API
+
+Once downloaded and installed in your application, it is time to make the API available in your pages. For that purpose, it is enough to load the API entry point script:
+
+```
+<script src="/ckeditor/build/ckeditor.js"></script>
+```
+
+For a more advanced setup, you may wish to bundle the CKEditor script with other scripts used by your application. See {@link TODO Bundling} for more information about it.
+
+Once the CKEditor script is loaded, you can {@link TODO use the API} to create editors in your page.
+

+ 43 - 0
docs/builds/guides/integration/plugins.md

@@ -0,0 +1,43 @@
+---
+# Scope:
+# * Introduction on plugins.
+# * Exemplify use cases.
+# * Point to resources to learn plugins development.
+
+title: Plugins
+category: builds-integration
+order: 40
+---
+
+Features in CKEditor are introduced by plugins. In fact, without plugins CKEditor is an empty API with no use. The builds provided with CKEditor 5 are actually a predefined collection of plugins, put together to satisfy specific needs.
+
+Plugins provided by the CKEditor core team are available in [npm](https://www.npmjs.com/search?q=ckeditor5) (and [GitHub](https://github.com/ckeditor?utf8=%E2%9C%93&q=ckeditor5&type=&language=) too) in form of npm packages. A package may contain one or more plugins (e.g. the [`@ckeditor/ckeditor5-image`](https://www.npmjs.com/package/@ckeditor/ckeditor5-image) packages contains several grannular plugins).
+
+## Common use cases
+
+Plugins can be pretty much anything. They’re simply code, initialized by the editor if they’re configured to be loaded. They can use the richness of the CKEditor 5 Framework API to enhance the editor or to better integrate it with your application.
+
+Common use cases for plugins are:
+
+* **Editing features**, like bold, heading, linking or whichever feature that interacts with the user on the manipulation of the contents.
+* **Adding semantic value** to the contents, like annotations or accessibility features.
+* **Third party services integration**, for injecting external resources inside the contents, like videos or social network posts.
+* **Handling image upload** and image manipulation features.
+* **Providing widgets** for easy integration with application structured data.
+* **Injecting analysis tools** that help enhancing the quality of the contents.
+* And other infinite possibilities…
+
+## Creating plugins
+
+Creating your own plugins is a straightforward task but it requires good knowledge about a few aspects of the CKEditor 5 development environment. The following resources are recommended as a starting point:
+
+* {@link TODO Plugin development guide}, in the CKEditor 5 Framework documentation.
+* {@link TODO Creating custom builds}, which is necessary to have your plugin included inside a CKEditor 5 build.
+
+A good understanding about the {@link TODO CKEditor 5 Framework} is also very welcome when it comes to creating plugins.
+
+## Using 3rd party plugins
+
+A great way to enhance your builds with additional features is by using plugins created by the community. Such plugins are generally available as npm packages, so a quick [search on the “ckeditor5” keyword in npm](https://www.npmjs.com/search?q=ckeditor5) should work as a starting point.
+
+Once you have plugins to be included, just {@link TODO create a custom build}, configured to include them.

+ 31 - 0
docs/builds/guides/license-and-legal.md

@@ -0,0 +1,31 @@
+---
+# Scope:
+# * Clarify copyright and license conditions.
+
+title: License and legal
+category: builds-guides
+order: 310
+---
+
+The following legal notices apply to CKEditor 5 Builds and all software from the CKEditor 5 Ecosystem included with it.
+
+Copyright (c) 2003-2017, CKSource Frederico Knabben. All rights reserved.
+
+Licensed under the terms of any of the following licenses at your choice:
+
+* [GNU General Public License Version 2 or later (the "GPL")](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html)
+* [GNU Lesser General Public License Version 2.1 or later (the "LGPL")](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html)
+* [Mozilla Public License Version 1.1 or later (the "MPL")](http://www.mozilla.org/MPL/MPL-1.1.html)
+
+You are not required to, but if you want to explicitly declare the license you have chosen to be bound to when using, reproducing, modifying and distributing this software, just include a text file titled "legal.txt" in your version of this software, indicating your license choice. In any case, your choice will not restrict any recipient of your version of this software to use, reproduce, modify and distribute this software under any of the above licenses.
+
+##  Sources of Intellectual Property Included in CKEditor
+
+Where not otherwise indicated, all CKEditor 5 Builds content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
+
+<!-- TODO 5 -->
+
+## Trademarks
+
+CKEditor is a trademark of [CKSource](http://cksource.com/) Frederico Knabben. All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.
+

+ 55 - 0
docs/builds/guides/migrate.md

@@ -0,0 +1,55 @@
+---
+# Scope:
+# * Introduction to the migration problem.
+# * Underline that migrating is a complex and important task.
+# * List and clarify the things that need attention when migrating.
+
+title: Migration
+category: builds-guides
+order: 30
+---
+
+When compared to its previous versions, CKEditor 5 can be considered a totally new editor. Every single aspect of it has been redesigned, from installation, to integration, to features, to its data model, to its API. Therefore, moving applications using previous version to version 5 cannot be called simply “upgrade”. It is something bigger, so the “migration” term fits better.
+
+There is no “drop in” solution for migrating. In this guide we hope to summarize the most important aspects to be taken in consideration.
+
+Before starting, be sure that migrating is your best choice. Check {@link TODO When NOT to use CKEditor 5 Builds}?
+
+## Installation and integration
+
+The very first aspect that changed with CKEditor 5 is its installation procedure. It became much more modern, with introduction of modular patterns, UMD, npm, etc. Check {@link TODO Installation} for more details.
+
+Once installed, the API for integrating CKEditor in your pages also changed. It's worth checking Basic API for an introduction.
+
+## Features
+
+When it comes to features, there are two aspects to be taken in consideration:
+
+* CKEditor 5 may still not have the same features available in CKEditor 4.
+* Existing features may behave differently.
+
+Therefore, it is worth spending good time analysing required features.
+
+CKEditor 5 has been designed with focus on creating quality content. Therefore, there are good reasons for it to not support some old features. You should take this chance to rethink features in your application, many times having to switch the approach towards a more modern reasoning.
+
+<!-- TODO 4 -->
+
+## Plugins
+
+The trickiest migration challenge to be faced may be related to custom plugins you could have had developed for CKEditor 4. Although their concept may stay the same, their implementation is certainly different and will require rewriting them from scratch.
+
+The same may apply for third party plugins, which may not have been yet ported to CKEditor 5.
+
+Check the {@link TODO Plugins guide} for more information on the development of plugins.
+
+## Themes (skins)
+
+In CKEditor 5, the previous concept of "skins” has been reviewed and is now called “themes”.
+
+If you have custom skins for CKEditor 4, these skins need to be recreated for CKEditor 5. Fortunately custom theming in CKEditor 5 is much more powerful and simpler than before. For more information, check how to {@link TODO create new themes in the CKEditor 5 Framework documentation}.
+
+## Existing data
+
+An extremely important aspect to be remembered is that, because of the difference on features, data produced with CKEditor 4 may not be compatible with CKEditor 5.
+
+Extensive analysis, data verification and tests should be performed on existing data. If necessary, conversion procedures should be developed to avoid data loss.

+ 79 - 0
docs/builds/guides/overview.md

@@ -0,0 +1,79 @@
+---
+# Scope:
+# * What is it?
+# * What are the use cases?
+# * What is the difference with CKEditor 5 Framework?
+# * What is the difference with CKEditor 4?
+
+title: Overview
+category: builds-guides
+order: 10
+---
+
+CKEditor 5 Builds are comprised by a set of ready to use rich-text editors, so called "builds", in different configurations. Our goal is providing easy to use solutions that can satisfy good part of the editing use cases out there.
+
+## Builds
+
+### Classic editor
+
+The classic "boxed" editing interface, with toolbar at the top:
+
+[ TODO: Classic Editor screenshot or sample ]
+
+### Inline Editor
+
+It leaves the contents as part of the page, attaching a floating toolbar to it:
+
+[ TODO: Inline Editor screenshot ]
+
+## How builds are designed
+
+Each build has been designed to satisfy as many use cases as possible. They differ on their UI/UX and features, based on the following approach:
+
+* Include the set of features proposed by the Editor Recommendations project.
+* Include features that contribute to creating quality content. In other words, features like fonts, colors and alignment are excluded.
+* Provide setups as generic as possible, based on research and community feedback.
+
+### Builds customization
+
+Although the default builds try to fit many cases, they may still not be perfect in some integrations. They may have either too many or too few features. They may not have your preferred theme or UI implementation. Customization is required then.
+
+Check Customize and extend for in-depth details on how to change the default builds to match your needs and preferences.
+
+## Use cases
+
+Each of the builds fits several different use cases. Just think about any possible use for writing rich-text in applications.
+
+The following are **some** common use cases:
+
+* In content management systems:
+	* Forms for writing articles or website content.
+	* Inline writing in a front-end-like editing page.
+	* In comments.
+* In marketing and sales automation applications:
+	* Composing e-mail campaigns.
+	* Creating templates.
+* In forum applications:
+	* For the creation of topics and their replies.
+* In team collaboration application:
+	* For the creation of shared documents.
+* Other uses:
+	* User profile editing pages.
+	* Book writing applications.
+	* Social messaging and content sharing.
+	* Creation of ads in recruitment software.
+
+### When NOT to use CKEditor 5 Builds?
+
+The {@link TODO CKEditor 5 Framework} should be used, instead of builds, in the following cases:
+
+* When you want to create your own text editor, having full control on every aspect of it, from UI to features.
+* When the solution proposed by the builds don't fit your specific use case.
+
+{@link TODO CKEditor 4} should be used instead, in the following cases:
+
+* When the compatibility with old browsers is a requirement.
+* If CKEditor 4 contains features that are essential for you, which are not available in CKEditor 5 yet.
+* If CKEditor 4 is already in use in you application and you're still not ready to replace it with CKEditor 5.
+
+<!-- TODO 1 -->

Fichier diff supprimé car celui-ci est trop grand
+ 29 - 0
docs/builds/guides/reporting-issues.md


+ 81 - 0
docs/builds/guides/whats-new.md

@@ -0,0 +1,81 @@
+---
+# Scope:
+# * Highlight new things, when compared to CKEditor 4.
+# * Emphasize cool new stuff we’re bringing, for those learning about CKEditor 5.
+
+title: What's new?
+category: builds-guides
+order: 20
+---
+
+## Enhanced UX
+
+### Better images
+
+Inserting images inside the contents is now very intuitive, with all technical aspects (uploading, resizing) hidden from the user experience. No more complex dialogs.
+
+[ TODO Animated GIF of Pasting ]
+
+[ TODO Animated GIF of DnD ]
+
+The outdated concept of image “alignment” has been dropped, introducing image “styles” instead:
+
+[ TODO Animated GIF on styles ]
+
+<!-- TODO 2 -->
+
+### Simple linking
+
+No more complex dialogs for linking.
+
+[ TODO Screenshot of a link with the edit balloon on it ]
+
+### Auto formatting
+
+Start lists, headings and even bold text by typing.
+
+[ TODO Animated GIF with auto formatting in action ]
+
+## Enhancement in the classic editor
+
+### New toolbar
+
+The toolbar is now always visible when the user scrolls the page down.
+
+[ TODO Animated GIF with scrolling and toolbar ]
+
+### Inlined contents
+
+The contents of the editor are now placed inline in the page. It’s much easier to style them. Additionally, the editor grows with the contents (or not, it’s up to you!).
+
+[ TODO Animated GIF of the editor growing when typing ]
+
+## Less features == Better content
+
+We focused on creating a tool for writing quality content. At the same time, we simplified the integration of the editor into your system.
+
+We had way too many features and configurations, which were confusing developers and at the same time negatively impacting on the end user experience. Misleading formatting tools have been removed, dialogs stripped out or simplified and well designed features that require no configuration.
+
+[ TODO Screenshot of the toolbar ]
+
+## Lightweight
+
+The editor is much more lightweight and fast. It brings a great user experience on both desktop and mobile devices.
+
+## Highly customizable
+
+CKEditor 5 Builds are based on the {@link TODO CKEditor 5 Framework}, which gives powerful customizability and extensibility possibilities.
+
+## Custom data model
+
+A much more efficient data model has been designed in CKEditor 5, making the development of features a much more creative experience and enhancing features like undo and redo.
+
+## Collaborative editing
+
+Another important benefit of our custom data model is that it enables the possibility of real-time collaborative editing inside CKEditor, by introducing the concepts of “operations” and “operational transformations”. Read more about {@link TODO collaboration in the CKEditor 5 Framework documentation}.
+
+<!-- TODO 3 -->
+
+## Modern
+
+CKEditor 5 has been totally rewritten in ES6, using the power of modules. It provides all the necessary tools to easily integrate it with modern applications and technologies, like Angular, React, Node.js, npm, etc.

+ 7 - 0
docs/builds/index.md

@@ -0,0 +1,7 @@
+---
+title: Builds
+category: builds
+order: 10
+---
+
+Builds' starting page.

docs/guides/end-user-features/end-user-features.md → docs/framework/guides/end-user-features/end-user-features.md


+ 1 - 1
docs/guides/getting-started/getting-started.md

@@ -3,4 +3,4 @@ title: Getting started
 category: getting-started
 order: 50
 ---
-Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.

+ 1 - 1
docs/guides/inserting-ckeditor/another-guide.md

@@ -3,4 +3,4 @@ title: Another guide about inserting CKEditor
 category: inserting-ckeditor
 order: 40
 ---
-Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.

+ 1 - 1
docs/guides/inserting-ckeditor/inserting.md

@@ -3,4 +3,4 @@ title: Inserting
 category: inserting-ckeditor
 order: 40
 ---
-Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.

+ 7 - 0
docs/framework/index.md

@@ -0,0 +1,7 @@
+---
+title: Framework
+category: framework
+order: 10
+---
+
+Framework's starting page.

+ 0 - 5
docs/guides/index.md

@@ -1,5 +0,0 @@
----
-title: Guides Index Page
-category: guides
-order: 10
----

+ 63 - 36
docs/umberto.json

@@ -12,61 +12,88 @@
 			"type": "jsdoc"
 		},
 		{
-			"name": "Guides",
-			"id": "guides",
-			"slug": "guides",
+			"name": "Framework",
+			"id": "framework",
+			"slug": "framework",
 			"categories": [
 				{
-					"name": "Getting started",
-					"id": "getting-started",
-					"slug": "getting-started",
-					"order": 10,
+					"name": "Guides",
+					"id": "framework-guides",
+					"slug": "guides",
 					"categories": [
 						{
-							"name": "Inserting CKEditor",
-							"id": "inserting-ckeditor",
-							"slug": "inserting-ckeditor",
-							"order": 10
+							"name": "Getting started",
+							"id": "getting-started",
+							"slug": "getting-started",
+							"categories": [
+								{
+									"name": "Inserting CKEditor",
+									"id": "inserting-ckeditor",
+									"slug": "inserting-ckeditor"
+								},
+								{
+									"name": "End User Features",
+									"id": "end-user-features",
+									"slug": "end-user-features"
+								}
+							]
 						},
 						{
-							"name": "End User Features",
-							"id": "end-user-features",
-							"order": 20
+							"name": "Plugins",
+							"id": "plugins",
+							"slug": "plugins"
 						}
 					]
 				},
-			  	{
-				  	"name": "Plugins",
-				  	"id": "plugins",
-				  	"slug": "plugins",
-				  	"order": 30
+				{
+					"name": "Tutorials",
+					"id": "tutorials",
+					"slug": "tutorials",
+					"categories": [
+						{
+							"name": "How to",
+							"id": "how-to",
+							"slug": "how-to",
+							"categories": [
+								{
+									"name": "Step by step",
+									"id": "step-by-step",
+									"slug": "step-by-step"
+								}
+							]
+						},
+						{
+							"name": "Advanced tutorials",
+							"id": "advanced-tutorials",
+							"slug": "advanced-tutorials"
+						}
+					]
 				}
 			]
 		},
 		{
-			"name": "Tutorials",
-			"id": "tutorials",
-			"slug": "tutorials",
+			"name": "Builds",
+			"id": "builds",
+			"slug": "builds",
 			"categories": [
 				{
-					"name": "How to",
-					"id": "how-to",
-					"slug": "how-to",
-					"order": 20,
+					"name": "Guides",
+					"id": "builds-guides",
+					"slug": "guides",
 					"categories": [
 						{
-							"name": "Step by step",
-							"id": "step-by-step",
-							"slug": "step-by-step",
-							"order": 10
+							"name": "Integration",
+							"id": "builds-integration",
+							"slug": "integration",
+							"order": 100
+						},
+						{
+							"name": "Development",
+							"id": "builds-development",
+							"slug": "development",
+							"order": 200
 						}
 					]
-				},
-				{
-					"name": "Advanced tutorials",
-					"id": "advanced-tutorials",
-					"slug": "advanced-tutorials",
-					"order": 10
 				}
 			]
 		}