瀏覽代碼

Docs: Added feature guide. [skip ci]

Piotrek Koszuliński 8 年之前
父節點
當前提交
513e7d4c9b

+ 5 - 0
packages/ckeditor5-heading/docs/_snippets/custom-heading-levels.html

@@ -0,0 +1,5 @@
+<div id="snippet-custom-heading-levels">
+	<h1>Heading 1</h1>
+	<h2>Heading 2</h2>
+	<p>This is <a href="https://ckeditor5.github.io">CKEditor&nbsp;5</a>.</p>
+</div>

+ 32 - 0
packages/ckeditor5-heading/docs/_snippets/custom-heading-levels.js

@@ -0,0 +1,32 @@
+/**
+ * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals console, window, document */
+
+import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
+
+import ArticlePreset from '@ckeditor/ckeditor5-presets/src/article';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-custom-heading-levels' ), {
+		plugins: [ ArticlePreset ],
+		toolbar: [ 'headings', 'bold', 'italic', 'link', 'unlink', 'bulletedList', 'numberedList', 'blockQuote', 'undo', 'redo' ],
+		image: {
+			toolbar: [ 'imageStyleFull', 'imageStyleSide', '|', 'imageTextAlternative' ]
+		},
+		heading: {
+			options: [
+				{ modelElement: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
+				{ modelElement: 'heading1', viewElement: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
+				{ modelElement: 'heading2', viewElement: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' }
+			]
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 84 - 0
packages/ckeditor5-heading/docs/heading.md

@@ -0,0 +1,84 @@
+---
+title: Headings
+category: features
+---
+
+The {@link module:heading/heading~Heading} feature enables support for headings.
+
+<info-box info>
+	This feature is enabled by default in all builds. It is also included in the {@link module:presets/article~Article Article preset}.
+</info-box>
+
+## Heading levels
+
+By default this feature is configured to support `<h2>`, `<h3>` and `<h4>` elements which are named accordingly "Heading 1", "Heading 2" and "Heading 3". The rationale behind starting from `<h2>` is that `<h1>` should be reserved for page's main title and the page's content will usually start from `<h2>`.
+
+<info-box hint>
+	You can read more about why the editor should not create `<h1>` elements in [Headings page of Editor Recommendations](http://ckeditor.github.io/editor-recommendations/features/headings.html).
+</info-box>
+
+### Configuring heading levels
+
+It is possible, of course, to configure which heading levels the editor should support and how should they be named in the Headings dropdown. Use the {@link module:heading/heading~HeadingConfig#options `heading.options`} config option to do so.
+
+The following editor will support only two levels of headings – `<h1>` and `<h2>`:
+
+```js
+ClassicEditor
+	.create( {
+		heading: {
+			options: [
+				{ modelElement: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
+				{ modelElement: 'heading1', viewElement: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
+				{ modelElement: 'heading2', viewElement: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' }
+			]
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+{@snippetTODO custom-heading-levels}
+
+Read more about the `heading.options` format in {@link module:heading/heading~HeadingConfig#options the option's API documentation}.
+
+## Installation
+
+To add this feature to your editor install the [`@ckeditor/ckeditor5-heading`](https://www.npmjs.com/package/@ckeditor/ckeditor5-heading) package:
+
+```
+npm install --save @ckeditor/ckeditor5-heading
+```
+
+And add it to your plugin list and toolbar configuration:
+
+```js
+import Heading from '@ckeditor/ckeditor5-heading/src/heading';
+
+ClassicEditor
+	.create( {
+		plugins: [ Heading, ... ],
+		toolbar: [ 'headings', ... ]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+If you are using editor build see how to {@linkTODO customize builds}.
+
+### Common API
+
+The {@link module:heading/heading~Heading} plugin registers:
+
+* the `'headings'` dropdown.
+* `'heading1'`, `'heading2'`, ..., `'headingN'` commands based on the {@link module:heading/heading~HeadingConfig#options `heading.options`} config option.
+
+	You can turn the currently selected block(s) to headings by executing one of these commands:
+
+	```js
+	editor.execute( 'heading2' );
+	```
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-heading.