Ver código fonte

Moar changes.

Piotrek Koszuliński 8 anos atrás
pai
commit
4933bec5f5

+ 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)!

+ 10 - 4
docs/builds/guides/integration/basic-api.md

@@ -4,6 +4,7 @@
 
 title: Basic API
 category: builds-integration
+order: 20
 ---
 
 ## Creators
@@ -14,24 +15,29 @@ 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 the same way with other creator classes.
+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 any of the above loaders is not available.
+* 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)/ckeditor.js', ( ClassicEditor ) => {
+require( '/(ckeditor path)/build/ckeditor.js', ClassicEditor => {
 	ClassicEditor.create; // [Function]
 } );
 
-// Or in all cases, just access it as a global.
+// As a global.
 ClassicEditor.create; // [Function]
 ```
 

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

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

@@ -4,14 +4,15 @@
 
 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)
+* [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.

+ 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.
+
+Each plugin is an independent project. For example, plugins provided by the CKEditor core team are available in GitHub and npm. That’s the case for the Basic Styles plugin, which provides the Bold feature, and the Heading plugin, to name a few.
+
+## 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.

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

@@ -4,8 +4,9 @@
 # * Underline that migrating is a complex and important task.
 # * List and clarify the things that need attention when migrating.
 
-title: Migration from previous versions
+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.

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

@@ -7,6 +7,7 @@
 
 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.

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

@@ -5,6 +5,7 @@
 
 title: What's new?
 category: builds-guides
+order: 20
 ---
 
 ## Enhanced UX

+ 5 - 0
docs/umberto.json

@@ -85,6 +85,11 @@
 							"name": "Integration",
 							"id": "builds-integration",
 							"slug": "integration"
+						},
+						{
+							"name": "Development",
+							"id": "builds-development",
+							"slug": "development"
 						}
 					]
 				}