Browse Source

Merge branch 'master' into t/513

Piotrek Koszuliński 8 years ago
parent
commit
2e07e571f8

+ 2 - 2
docs/builds/guides/migrate.md

@@ -4,9 +4,9 @@
 # * Underline that migrating is a complex and important task.
 # * List and clarify the things that need attention when migrating.
 
-title: Migration
+title: Migration from CKEditor 4
 category: builds-guides
-order: 30
+order: 260
 ---
 
 When compared to its previous versions, CKEditor 5 should be considered **a totally new editor**. Every single aspect of it was redesigned, from installation, to integration, to features, to its data model, and finally to its API. Therefore, moving applications using a previous version to version 5 cannot be simply called an "upgrade". It is something bigger, so the "migration" term fits better.

+ 32 - 20
docs/builds/guides/overview.md

@@ -10,14 +10,22 @@ category: builds-guides
 order: 10
 ---
 
-CKEditor 5 Builds are a set of ready to use rich-text editors. Every "build" provides a single type of editor with a set of features and a default configuration. Our goal is to provide easy to use solutions that can satisfy a good part of the editing use cases out there.
+CKEditor 5 Builds are a set of ready to use rich text editors. Every "build" provides a single type of editor with a set of features and a default configuration. They provide easy to use solutions that can be installed with no effort and that satisfy the most common editing use cases.
 
-## Builds
+## Available builds
+
+The following CKEditor 5 Builds are currently available:
+
+ * [Classic editor](#Classic-editor)
+ * [Inline editor](#Inline-editor)
+ * [Balloon toolbar editor](#Balloon-toolbar-editor)
 
 ### Classic editor
 
 Classic editor is what most users traditionally learnt to associate with a rich text editor — a toolbar with an editing area placed in a specific position on the page, usually as a part of a form that you use to submit some content to the server.
 
+The editor during initialisation hides given element on a page and renders "instead" of it, that's why it's usually used to replace `<textarea>` elements.
+
 In CKEditor 5 the concept of the "boxed" editor was reinvented:
 
  * The toolbar is now always visible when user scrolls the page down.
@@ -30,33 +38,23 @@ To try it out, check the {@link examples/builds/classic-editor classic editor ex
 
 ### Inline editor
 
-The edited content remains a part of the page, with a floating toolbar attached:
+Inline editor comes with a floating toolbar, which becomes visible when the editor is focused (e.g. by clicking on it). Unlike classic editor, inline editor does not render "instead" of a given element, it simply makes it editable. As a consequence the styles of the edited content will be exactly the same before and after the editor is created.
+
+A common scenario for using inline editor is offering users the possibility to edit content in its real location in a web page, instead of doing it in a separate administration section.  
 
 {@img assets/img/editor-inline.png 774 Screenshot of an inline editor.}
 
 To try it out, check the {@link examples/builds/inline-editor inline editor example}.
 
-### Editor with balloon toolbar
+### Balloon toolbar editor
 
-The edited content remains a part of the page (like in the inline editor). The toolbar appears in a balloon next to the selection (when the selection is not empty):
+Balloon toolbar editor is very similar to the inline editor. The difference between them is that the toolbar appears in a balloon next to the selection (when the selection is not empty):
 
 {@img assets/img/editor-balloon-toolbar.png 779 Screenshot of a baloon toolbar editor.}
 
 To try it out, check the {@link examples/builds/balloon-toolbar-editor balloon toolbar editor example}.
 
-## How builds are designed
-
-Each build was designed to satisfy as many use cases as possible. They differ in their UI, UX and features, and are based on the following approach:
-
-* Include the set of features proposed by the [Editor Recommendations project](https://ckeditor.github.io/editor-recommendations/).
-* Include features that contribute to creating quality content.
-* Provide setups as generic as possible, based on research and community feedback.
-
-<info-box>
-	Features like fonts, colors and alignment will be introduced in the future, when the new types of builds will be introduced with the purpose of satisfying document editing scenarios.
-</info-box>
-
-### Build customization
+## Builds customization
 
 Every build comes with a default set of features and a default configuration of them. Although the builds try to fit many cases, they may still need to be adjusted in some integrations. The following modifications are possible:
 
@@ -68,7 +66,21 @@ Read more in the {@link builds/guides/integration/configuration Configuration gu
 
 If a build doesn't provide all the necessary features or you want create a highly optimized build of editor which will contain only the necessary features, then you need to customize the build or create a brand new one. Check {@link builds/guides/development/custom-builds Custom builds} for details on how to change the default builds to match your preferences.
 
-## Use cases
+## Additional information
+
+### How builds were designed
+
+Each build was designed to satisfy as many use cases as possible. They differ in their UI, UX and features, and are based on the following approach:
+
+* Include the set of features proposed by the [Editor Recommendations project](https://ckeditor.github.io/editor-recommendations/).
+* Include features that contribute to creating quality content.
+* Provide setups as generic as possible, based on research and community feedback.
+
+<info-box>
+	Features like fonts, colors and alignment will be introduced in the future, when the new types of builds will be introduced with the purpose of satisfying document editing scenarios.
+</info-box>
+
+### Use cases
 
 Each of the builds fits several different use cases. Just think about any possible use for writing rich-text in applications.
 
@@ -91,7 +103,7 @@ The following are **some** common use cases:
 	* Social messaging and content sharing.
 	* Creation of ads in recruitment software.
 
-### When NOT to use CKEditor 5 builds?
+### When NOT to use builds?
 
 The {@link framework/index CKEditor 5 Framework} should be used, instead of builds, in the following cases:
 

+ 133 - 0
docs/builds/guides/quick-start.md

@@ -0,0 +1,133 @@
+---
+# Scope:
+# * TL;DR I want to run CKEditor 5.
+
+title: Quick start
+category: builds-guides
+order: 30
+---
+
+Creating an editor using CKEditor 5 build is very simple and in short can be described in two steps:
+ 
+1. Load the desired editor via `<script>` tag.
+2. Call the static `create` method to create the editor.
+
+## Classic editor
+
+In your HTML page add an element that CKEditor should replace:
+```
+<textarea name="editor1" id="text-editor"></textarea>
+```
+
+Load CKEditor 5, the classic editor build (here [CDN](https://cdn.ckeditor.com/) location is used):
+```
+<script src="https://cdn.ckeditor.com/ckeditor5-build-classic/0.11.0/build/ckeditor.js"></script>
+```
+
+Call the {@link module:editor-classic/classiceditor~ClassicEditor#create `ClassicEditor#create`} method.
+```
+<script>
+	ClassicEditor.create( document.querySelector( '#text-editor' ) );
+</script>
+```
+
+### Example
+
+```
+<!DOCTYPE html>
+<html>
+<head>
+	<meta charset="utf-8">
+	<title>CKEditor 5 - Classic editor</title>
+	<script src="https://cdn.ckeditor.com/ckeditor5-build-classic/0.11.0/build/ckeditor.js"></script>
+</head>
+<body>
+<h1>Classic editor</h1>
+<textarea name="editor1" id="text-editor"></textarea>
+<script>
+	ClassicEditor.create( document.querySelector( '#text-editor' ) );
+</script>
+</body>
+</html>
+```
+
+## Inline editor
+
+In your HTML page add an element that CKEditor should make editable:
+```
+<div id="text-editor"></textarea>
+```
+
+Load CKEditor 5, the inline editor build (here [CDN](https://cdn.ckeditor.com/) location is used):
+```
+<script src="https://cdn.ckeditor.com/ckeditor5-build-inline/0.11.0/build/ckeditor.js"></script>
+```
+
+Call the {@link module:editor-inline/inlineeditor~InlineEditor#create `InlineEditor#create`} method.
+```
+<script>
+	InlineEditor.create( document.querySelector( '#text-editor' ) );
+</script>
+```
+
+### Example
+
+```
+<!DOCTYPE html>
+<html>
+<head>
+	<meta charset="utf-8">
+	<title>CKEditor 5 - Inline editor</title>
+	<script src="https://cdn.ckeditor.com/ckeditor5-build-inline/0.11.0/build/ckeditor.js"></script>
+</head>
+<body>
+<h1>Inline editor</h1>
+<div id="text-editor">This is some sample content.</div>
+<script>
+	InlineEditor.create( document.querySelector( '#text-editor' ) );
+</script>
+</body>
+</html>
+```
+## Balloon toolbar editor
+
+In your HTML page add an element that CKEditor should make editable:
+```
+<div id="text-editor"></textarea>
+```
+
+Load CKEditor 5, the balloon toolbar editor build (here [CDN](https://cdn.ckeditor.com/) location is used):
+```
+<script src="https://cdn.ckeditor.com/ckeditor5-build-balloon-toolbar/0.11.0/build/ckeditor.js"></script>
+```
+
+Call the {@link module:editor-balloon-toolbar/balloontoolbareditor~BalloonToolbarEditor#create `BalloonToolbarEditor#create`} method.
+```
+<script>
+	BalloonToolbarEditor.create( document.querySelector( '#text-editor' ) );
+</script>
+```
+
+### Example
+
+```
+<!DOCTYPE html>
+<html>
+<head>
+	<meta charset="utf-8">
+	<title>CKEditor 5 - Balloon toolbar editor</title>
+	<script src="https://cdn.ckeditor.com/ckeditor5-build-balloon-toolbar/0.11.0/build/ckeditor.js"></script>
+</head>
+<body>
+<h1>Balloon toolbar editor</h1>
+<div id="text-editor">This is some sample content.</div>
+<script>
+	BalloonToolbarEditor.create( document.querySelector( '#text-editor' ) );
+</script>
+</body>
+</html>
+```
+
+## Next steps
+
+Check the {@link builds/guides/integration/configuration Configuration guide} to learn how to configure the editor, e.g. change the default toolbar.

+ 2 - 1
docs/builds/guides/whats-new.md

@@ -3,7 +3,8 @@
 # * Highlight new things when compared to CKEditor 4.
 # * Emphasize cool new stuff we are bringing, for those learning about CKEditor 5.
 
-title: What's new?
+title: What's new in CKEditor 5?
+menu-title: What's new?
 category: builds-guides
 order: 20
 ---

+ 3 - 1
gulpfile.js

@@ -52,6 +52,7 @@ gulp.task( 'docs', () => {
 
 		return runUmberto( {
 			skipLiveSnippets,
+			skipApi,
 			production
 		} );
 	}
@@ -93,7 +94,8 @@ function runUmberto( options ) {
 		skipLiveSnippets: options.skipLiveSnippets,
 		snippetOptions: {
 			production: options.production
-		}
+		},
+		skipApi: options.skipApi
 	} );
 }
 

+ 13 - 3
scripts/docs/snippet-adapter/snippetadapter.js

@@ -16,6 +16,10 @@ const BabelMinifyPlugin = require( 'babel-minify-webpack-plugin' );
 const webpackProcesses = new Map();
 
 module.exports = function snippetAdapter( data ) {
+	if ( !data.snippetSource.js ) {
+		throw new Error( `Missing snippet source for "${ data.snippetPath }".` );
+	}
+
 	const snippetConfig = readSnippetConfig( data.snippetSource.js );
 	const outputPath = path.join( data.outputPath, data.snippetPath );
 	let sassImportPath;
@@ -80,9 +84,15 @@ function getWebpackConfig( config ) {
 
 	if ( config.minify ) {
 		plugins.push(
-			new BabelMinifyPlugin( null, {
-				comments: false
-			} )
+			new BabelMinifyPlugin(
+				{
+					// Temporary workaround for https://github.com/ckeditor/ckeditor5/issues/542.
+					mangle: false
+				},
+				{
+					comments: false
+				}
+			)
 		);
 	}