Переглянути джерело

Merge pull request #8133 from ckeditor/i/8129

Docs: Added a new block quote feature guide.
Anna Tomanek 5 роки тому
батько
коміт
4de0e05c10

+ 27 - 0
packages/ckeditor5-block-quote/docs/_snippets/features/block-quote.html

@@ -0,0 +1,27 @@
+<div id="snippet-block-quote">
+	<h3>The Famous Einstein Quote that never was</h3>
+
+	<p>All of us &mdash; well, maybe most of us &mdash; have encountered the following quote in the past few years:</p>
+
+	<blockquote>
+		<p>Everybody is a genius. But if you judge a fish by its ability to climb a tree, it will live its whole life believing that it is stupid.</p>
+
+		<p>Albert Einstein</p>
+	</blockquote>
+
+	<p>It is mostly popular on Facebook and other social networks, where people share it aplenty. No wonder, as it sounds great, it sounds smart, it is neat and, well, let&rsquo;s be frank &mdash; Albert is one hell of a figure!</p>
+
+	<p>The truth, however, is not as neat, not as great and people who mindlessly forward the quote are not as smart. Because, in fact, Einstein has never said that. It comes from a 2004 book &ldquo;The Rhythm of Life: Living Every Day with Passion and Purpose&rdquo; by Mathew Kelly, published almost 50 years after Albert&rsquo;s death in 1955.</p>
+
+	<p>He was, most probably, inspired by an essay by Amos E. Dolbear of Tufts titled &ldquo;An Educational Allegory&rdquo;, describing animals educated to work on their weakest features instead of their strongest ones. So an eagle was made to run, a penguin was forced to fly and so on. There is also the 1903 &ldquo;Jungle School Boards&rdquo; fable from an Illinois newspaper in which a monkey, a kangaroo and an elephant cannot agree on the curriculum for their animal school &mdash; should little animals be taught tree-climbing, jumping or looking wise?&nbsp;</p>
+
+	<p>In the late 1940s, something that appears to be an amalgam of the two was published and later reprinted with various changes in the 1960s. The idea evolved for decades and got mixed up with a few other quotes about being a genius originating back to the 1970s. Finally, Kelly wrote in his 2004 book:</p>
+
+	<blockquote>
+		<p>Albert Einstein wrote, &ldquo;Everybody is a genius. But if you judge a fish by its ability to climb a tree, it will live its whole life believing that it is stupid.&rdquo; The question I have for you at this point of our journey together is, &ldquo;What is your genius?&rdquo;</p>
+	</blockquote>
+
+	<p>Why he attributed this to Albert Einstein remains unclear. The fact is, the quote got popular. But apparently not everybody is a genius when it comes to fact-checking and sources...</p>
+
+</div>
+

+ 38 - 0
packages/ckeditor5-block-quote/docs/_snippets/features/block-quote.js

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-block-quote' ), {
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'link',
+				'|',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'blockQuote',
+				'outdent',
+				'indent',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err );
+	} );

+ 6 - 2
packages/ckeditor5-block-quote/docs/api/block-quote.md

@@ -8,13 +8,17 @@ category: api-reference
 
 This package implements block quote support for CKEditor 5.
 
+## Demo
+
+Check out the {@link features/block-quote#demo demo in the Block quote feature} guide.
+
 ## Documentation
 
-See the {@link module:block-quote/blockquote~BlockQuote} plugin documentation.
+See the {@link features/block-quote Block quote feature} guide and the {@link module:block-quote/blockquote~BlockQuote} plugin documentation.
 
 ## Installation
 
-```bash
+```
 npm install --save @ckeditor/ckeditor5-block-quote
 ```
 

+ 69 - 0
packages/ckeditor5-block-quote/docs/features/block-quote.md

@@ -0,0 +1,69 @@
+---
+category: features
+menu-title: Block quote
+---
+
+# Block quote
+
+The {@link module:block-quote/blockquote~BlockQuote} feature allows you to easily include block quotations or pull quotes in the rich-text content. This provides an attractive way to draw the readers' attention to selected parts of text. It also helps organize the content in a structured, elegant way and to manage the flow better.
+
+## Demo
+
+Use the editor below to see the block quote plugin in action.
+
+{@snippet features/block-quote}
+
+## Installation
+
+To add this feature to your rich-text editor, install the [`@ckeditor/ckeditor5-block-quote`](https://www.npmjs.com/package/@ckeditor/ckeditor5-block-quote) package:
+
+```plaintext
+npm install --save @ckeditor/ckeditor5-block-quote
+```
+
+And add it to your plugin list configuration:
+
+```js
+import BlockQuote from '@ckeditor/ckeditor5-block-quote/src/blockquote';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ BlockQuote, ... ],
+		toolbar: [ 'blockQuote', ... ]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
+## Related features
+
+Here are some other CKEditor 5 features that you can use similarly to the block quote plugin to structure your text better:
+
+* The {@link features/indent block indentation feature} allows you to set indentation for text blocks such as paragraphs or lists.
+* The {@link features/code-blocks code block feature} allows for insertion of various code listings.
+
+## Common API
+ 
+The {@link module:block-quote/blockquote~BlockQuote} plugin registers:
+
+* the `'blockQuote'` UI button component implemented by the {@link module:block-quote/blockquoteui~BlockQuoteUI block quote UI feature},
+* the `'blockQuote'` command implemented by the {@link module:block-quote/blockquoteediting~BlockQuoteEditing block quote editing feature}.
+
+The command can be executed using the {@link module:core/editor/editor~Editor#execute `editor.execute()`} method:
+
+```js
+// Applies block quote to the selected content.
+editor.execute( 'blockQuote' );
+```
+
+<info-box>
+	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
+</info-box>
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-block-quote.