From 9799d133c02dd84e673de39becc02573a2f2fce7 Mon Sep 17 00:00:00 2001 From: Filip Sobol Date: Wed, 9 Oct 2024 15:44:01 +0200 Subject: [PATCH] Docs: Use `npx degit` instead of `git clone` in tutorials (#17232) Docs: Use `npx degit` instead of `git clone` in tutorials. See #17182. --- .../abbreviation-plugin-level-1.md | 48 +++-------------- .../abbreviation-plugin-level-2.md | 10 +++- .../abbreviation-plugin-level-3.md | 10 +++- docs/tutorials/crash-course/editor.md | 15 +++--- .../creating-simple-plugin-timestamp.md | 48 ++++++----------- .../widgets/data-from-external-source.md | 31 ++++------- .../widgets/implementing-a-block-widget.md | 50 ++++-------------- .../widgets/implementing-an-inline-widget.md | 51 ++++--------------- .../widgets/using-react-in-a-widget.md | 18 ++++--- 9 files changed, 87 insertions(+), 194 deletions(-) diff --git a/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-1.md b/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-1.md index a6b8d0c3554..0942edd9ddb 100644 --- a/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-1.md +++ b/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-1.md @@ -18,18 +18,20 @@ If you want to see the final product of this tutorial before you plunge in, chec ## Let's start! -The easiest way to set up your project is to grab the starter files from the [GitHub repository for this tutorial](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/abbreviation-plugin). We gathered all the necessary dependencies there, including some CKEditor 5 packages and other files needed to start the editor. - -The editor has already been created in the `main.js` file with some basic plugins. All you need to do is clone the repository, navigate to the [starter-files directory](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/abbreviation-plugin/starter-files), run the `npm install` command, and you can start coding right away. +The easiest way to get started is to grab the starter project using the commands below. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/abbreviation-plugin/starter-files +npx -y degit ckeditor/ckeditor5-tutorials-examples/abbreviation-plugin/starter-files abbreviation-plugin +cd abbreviation-plugin npm install npm run dev ``` +This will create a new directory called `abbreviation-plugin` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server. + +The editor with some basic plugins is created in the `main.js` file. + The starter files come with the {@link framework/development-tools/inspector CKEditor 5 Inspector} attached to the editor, so you can debug and observe what is happening in the model and the view layers. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more. @@ -105,18 +107,6 @@ Now, we need to load the `Abbreviation` plugin in our `main.js` file. The editor ```js // main.js -import { - ClassicEditor, - Essentials, - Paragraph, - Heading, - List, - Bold, - Italic -} from 'ckeditor5'; - -import 'ckeditor5/ckeditor5.css'; - import Abbreviation from './abbreviation/abbreviation'; // ADDED ClassicEditor @@ -126,12 +116,6 @@ ClassicEditor Abbreviation // ADDED ], toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList' ] - } ) - .then( editor => { - console.log( 'Editor was initialized', editor ); - } ) - .catch( error => { - console.error( error.stack ); } ); ``` @@ -327,18 +311,6 @@ We passed the name of the button in the `componentFactory.add`, so it is now ava ```js // main.js -import { - ClassicEditor, - Essentials, - Paragraph, - Heading, - List, - Bold, - Italic -} from 'ckeditor5'; - -import 'ckeditor5/ckeditor5.css'; - import Abbreviation from './abbreviation/abbreviation'; ClassicEditor @@ -351,12 +323,6 @@ ClassicEditor '|', 'abbreviation' // ADDED ] - } ) - .then( editor => { - console.log( 'Editor was initialized', editor ); - } ) - .catch( error => { - console.error( error.stack ); } ); ``` diff --git a/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-2.md b/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-2.md index 021b4bb413f..518c94dac7e 100644 --- a/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-2.md +++ b/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-2.md @@ -10,7 +10,15 @@ modified_at: 2022-07-15 In this part of the tutorial we will focus on creating a dialog, which will get the user's input. -We will pick up where we left off in the first part, so make sure you {@link tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-1 start there}, or grab our [starter files for this part](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/abbreviation-plugin/part-1). +We will pick up where we left off in the first part, so make sure you {@link tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-1 start there} or grab our starter files for this part using the commands below. + +```bash +npx -y degit ckeditor/ckeditor5-tutorials-examples/abbreviation-plugin/part-1 abbreviation-plugin +cd abbreviation-plugin + +npm install +npm run dev +``` As we will mostly work on the UI, we recommend reading about our {@link framework/architecture/ui-library UI library} before you start coding. diff --git a/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-3.md b/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-3.md index 7838861f97b..eecaebbeb0a 100644 --- a/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-3.md +++ b/docs/tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-3.md @@ -10,7 +10,15 @@ modified_at: 2022-07-15 You made it to the final part of the abbreviation plugin tutorial. In this part, we will improve accessibility of our plugin. We will also work on a command, which will additionally grab the text from user's selection, and insert it into our form. And more! -We pick up where we left off in the {@link tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-2 second part}, so make sure you finished it, or grab our [starter files for this part](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/abbreviation-plugin/part-2). +We pick up where we left off in the {@link tutorials/abbreviation-plugin-tutorial/abbreviation-plugin-level-2 second part}, so make sure you finished it, or grab our starter files for this part using the commands below. + +```bash +npx -y degit ckeditor/ckeditor5-tutorials-examples/abbreviation-plugin/part-2 abbreviation-plugin +cd abbreviation-plugin + +npm install +npm run dev +``` If you want to see the final product of this tutorial before you plunge in, check out the [live demo](#demo). diff --git a/docs/tutorials/crash-course/editor.md b/docs/tutorials/crash-course/editor.md index a69b4444026..e1099fc7ab4 100644 --- a/docs/tutorials/crash-course/editor.md +++ b/docs/tutorials/crash-course/editor.md @@ -11,14 +11,17 @@ modified_at: 2023-08-16 ## Test environment -For the purposes of this tutorial, we have created a repository with the minimal setup required to use the editor. To follow along: +For this tutorial, we have created a minimal setup required to use the editor. To follow along, run the commands below: -1. Clone [this repository](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/crash-course). -2. Run the `npm install` command to install the dependencies. -3. Run the `npm run dev` command to start the project. -4. Open the URL displayed in your terminal. +```bash +npx -y degit ckeditor/ckeditor5-tutorials-examples/crash-course crash-course +cd crash-course -If everything went well, you should see a "Hello world!" text displayed on the page. +npm install +npm run dev +``` + +Open the URL displayed in your terminal. If everything went well, you should see a "Hello world!" text displayed on the page. We encourage you to follow the steps in the tutorial and type the code yourself to build the muscle and mental memory. diff --git a/docs/tutorials/creating-simple-plugin-timestamp.md b/docs/tutorials/creating-simple-plugin-timestamp.md index a0ededac2e0..fd9acae11d3 100644 --- a/docs/tutorials/creating-simple-plugin-timestamp.md +++ b/docs/tutorials/creating-simple-plugin-timestamp.md @@ -13,38 +13,34 @@ We will create a toolbar button that will insert the current date and time at th ## Let's start! -The easiest way to set up your project is to grab the starter files from our [GitHub repository for this tutorial](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/timestamp-plugin). We gathered all the necessary dependencies there, including some CKEditor 5 packages and other files needed to run the editor. - -The editor has already been created in the `main.js` file with some basic plugins. All you need to do is clone the repository, run the `npm install` command, and you can start coding right away. +The easiest way to get started is to grab the starter project using the commands below. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/timestamp-plugin/starter-files +npx -y degit ckeditor/ckeditor5-tutorials-examples/timestamp-plugin/starter-files timestamp-plugin +cd timestamp-plugin npm install npm run dev ``` -## Creating a plugin +This will create a new directory called `timestamp-plugin` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server. -All features in the CKEditor 5 are powered by plugins. To create our custom timestamp plugin, we need to import the base `Plugin` class. +The editor with some basic plugins is created in the `main.js` file. -We can now create a `Timestamp` class that extends the basic `Plugin` class. After we define it, we can add it to the editor's plugins array. +## Creating a plugin + +All features in the CKEditor 5 are powered by plugins. To create our custom timestamp plugin, we need to import the base `Plugin` class from the `ckeditor5`. Be careful not to remove the other imports from this package. ```js -import { - ClassicEditor, - Essentials, - Paragraph, - Heading, - List, - Bold, - Italic, +import { + // Other imports Plugin } from 'ckeditor5'; +``` -import 'ckeditor5/ckeditor5.css'; +We can now create a `Timestamp` class that extends the basic `Plugin` class. After we define it, we can add it to the editor's plugins array. +```js class Timestamp extends Plugin { init() { console.log( 'Timestamp was initialized.' ); @@ -56,14 +52,7 @@ ClassicEditor // Add the Timestamp plugin to config.plugins array. plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, Timestamp - ], - toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList' ] - } ) - .then( editor => { - console.log( 'Editor was initialized', editor ); - } ) - .catch( error => { - console.error( error.stack ); + ] } ); ``` @@ -81,14 +70,7 @@ We also need to register our button in the editor's UI `componentFactory`, so it ```js import { - ClassicEditor, - Essentials, - Paragraph, - Heading, - List, - Bold, - Italic, - Plugin, + // Other imports ButtonView } from 'ckeditor5'; diff --git a/docs/tutorials/widgets/data-from-external-source.md b/docs/tutorials/widgets/data-from-external-source.md index 17ca5350952..b37dbe73af7 100644 --- a/docs/tutorials/widgets/data-from-external-source.md +++ b/docs/tutorials/widgets/data-from-external-source.md @@ -23,18 +23,20 @@ This guide assumes that you are familiar with the widgets concept introduced in The overall project structure will be similar to one described in the {@link tutorials/widgets/implementing-an-inline-widget#bootstrapping-the-project Bootstrapping the project} section of the "Implementing an inline widget" tutorial. -The easiest way to set up your project is to grab the starter files from the [GitHub repository for this tutorial](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/data-from-external-source). We gathered all the necessary dependencies there, including some CKEditor 5 packages and other files needed to start the editor. - -The editor has already been created in the `main.js` file with some basic plugins. All you need to do is clone the repository, navigate to the [starter-files directory](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/data-from-external-source/starter-files), run the `npm install` command, and you can start coding right away. +The easiest way to get started is to grab the starter project using the commands below. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/data-from-external-source/starter-files +npx -y degit ckeditor/ckeditor5-tutorials-examples/data-from-external-source/starter-files data-from-external-source +cd data-from-external-source npm install npm run dev ``` +This will create a new directory called `data-from-external-source` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server. + +The editor with some basic plugins is created in the `main.js` file. + First, lets define the `ExternalDataWidget` plugin. The project structure should be as follows: ```plain @@ -104,27 +106,12 @@ Finally, you need to load the `ExternalDataWidget` plugin in your `main.js` file ```js // main.js -import { ClassicEditor, Bold, Italic, Essentials, Heading, List, Paragraph } from 'ckeditor5'; import ExternalDataWidget from './external-data-widget/externaldatawidget'; -import CKEditorInspector from '@ckeditor/ckeditor5-inspector'; - -import 'ckeditor5/ckeditor5.css'; ClassicEditor .create( document.querySelector( '#editor' ), { plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, ExternalDataWidget ], toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', '|', 'undo', 'redo' ] - } ) - .then( editor => { - console.log( 'Editor was initialized', editor ); - - CKEditorInspector.attach( { editor: 'editor' } ); - - // Expose for playing in the console. - window.editor = editor; - } ) - .catch( error => { - console.error( error.stack ); } ); ``` @@ -576,8 +563,8 @@ You can see the external data widget implementation in action in the editor belo If you got lost at any point in the tutorial or want to go straight to the solution, there is a repository with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/data-from-external-source/final-project) available. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/data-from-external-source/final-project +npx -y degit ckeditor/ckeditor5-tutorials-examples/data-from-external-source/final-project final-project +cd final-project npm install npm run dev diff --git a/docs/tutorials/widgets/implementing-a-block-widget.md b/docs/tutorials/widgets/implementing-a-block-widget.md index 900ffed63b0..17da6210182 100644 --- a/docs/tutorials/widgets/implementing-a-block-widget.md +++ b/docs/tutorials/widgets/implementing-a-block-widget.md @@ -26,19 +26,21 @@ This tutorial will reference various parts of the {@link framework/architecture/ ## Let's start -The easiest way to set up your project is to grab the starter files from the [GitHub repository for this tutorial](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/block-widget). We gathered all the necessary dependencies there, including some CKEditor 5 packages and other files needed to start the editor. - -The editor has already been created in the `main.js` file with some basic plugins. All you need to do is clone the repository, navigate to the [starter-files directory](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/block-widget/starter-files), run the `npm install` command, and you can start coding right away. +The easiest way to get started is to grab the starter project using the commands below. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/block-widget/starter-files +npx -y degit ckeditor/ckeditor5-tutorials-examples/block-widget/starter-files block-widget +cd block-widget npm install npm run dev ``` -You should see a CKEditor 5 instance in your browser like this: +This will create a new directory called `block-widget` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server. + +The editor with some basic plugins is created in the `main.js` file. + +Open the URL displayed in your terminal. If everything went well, you should see a CKEditor 5 instance in your browser like this: {@img assets/img/tutorial-implementing-a-widget-1.png Screenshot of a classic editor initialized from source.} @@ -109,16 +111,6 @@ Finally, you need to load the `SimpleBox` plugin in your `main.js` file: ```js // main.js -import { - ClassicEditor, - Bold, - Italic, - Essentials, - Heading, - List, - Paragraph -} from 'ckeditor5'; - import SimpleBox from './simplebox/simplebox'; // ADDED ClassicEditor @@ -128,15 +120,6 @@ ClassicEditor SimpleBox // ADDED ], toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList' ] - } ) - .then( editor => { - console.log( 'Editor was initialized', editor ); - - // Expose for playing in the console. - window.editor = editor; - } ) - .catch( error => { - console.error( error.stack ); } ); ``` @@ -366,16 +349,6 @@ To learn that, use the official {@link framework/development-tools/inspector CKE ```js // main.js -import { - ClassicEditor, - Bold, - Italic, - Essentials, - Heading, - List, - Paragraph -} from 'ckeditor5'; - import SimpleBox from './simplebox/simplebox'; import CKEditorInspector from '@ckeditor/ckeditor5-inspector'; // ADDED @@ -394,9 +367,6 @@ ClassicEditor CKEditorInspector.attach( { 'editor': editor } ); window.editor = editor; - } ) - .catch( error => { - console.error( error.stack ); } ); ``` @@ -838,8 +808,8 @@ You can see the block widget implementation in action in the editor below. You c If you got lost at any point in the tutorial or want to go straight to the solution, there is a repository with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/block-widget/final-project) available. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/block-widget/final-project +npx -y degit ckeditor/ckeditor5-tutorials-examples/block-widget/final-project final-project +cd final-project npm install npm run dev diff --git a/docs/tutorials/widgets/implementing-an-inline-widget.md b/docs/tutorials/widgets/implementing-an-inline-widget.md index 4260d84f750..89159df1885 100644 --- a/docs/tutorials/widgets/implementing-an-inline-widget.md +++ b/docs/tutorials/widgets/implementing-an-inline-widget.md @@ -26,18 +26,20 @@ This guide assumes that you are familiar with the widgets concept introduced in ## Bootstrapping the project -The easiest way to set up your project is to grab the starter files from the [GitHub repository for this tutorial](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/inline-widget/starter-files). We gathered all the necessary dependencies there, including some CKEditor 5 packages and other files needed to start the editor. - -The editor has already been created in the `main.js` file with some basic plugins. All you need to do is clone the repository, navigate to the starter-files directory, run the `npm install` command, and you can start coding right away. +The easiest way to get started is to grab the starter project using the commands below. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/inline-widget/starter-files +npx -y degit ckeditor/ckeditor5-tutorials-examples/inline-widget/starter-files inline-widget +cd inline-widget npm install npm run dev ``` +This will create a new directory called `inline-widget` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server. + +The editor with some basic plugins is created in the `main.js` file. + First, let's define the `Placeholder` plugin. The project should have a structure shown below: ```plain @@ -107,27 +109,12 @@ Finally, you need to load the `Placeholder` plugin in your `main.js` file: ```js // main.js -import { ClassicEditor, Bold, Italic, Essentials, Heading, List, Paragraph } from 'ckeditor5'; import Placeholder from './placeholder/placeholder'; -import CKEditorInspector from '@ckeditor/ckeditor5-inspector'; - -import 'ckeditor5/ckeditor5.css'; ClassicEditor .create( document.querySelector( '#editor' ), { plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, Placeholder ], toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', '|', 'undo', 'redo' ] - } ) - .then( editor => { - console.log( 'Editor was initialized', editor ); - - CKEditorInspector.attach( { editor: 'editor' } ); - - // Expose for playing in the console. - window.editor = editor; - } ) - .catch( error => { - console.error( error.stack ); } ); ``` @@ -523,34 +510,14 @@ Add the dropdown to the toolbar: ```js // main.js -import { - ClassicEditor, - Bold, - Italic, - Essentials, - Heading, - List, - Paragraph -} from 'ckeditor5'; - import Placeholder from './placeholder/placeholder'; -import CKEditorInspector from '@ckeditor/ckeditor5-inspector'; - ClassicEditor .create( document.querySelector( '#editor' ), { plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, Placeholder ], // Insert the "placeholder" dropdown into the editor toolbar. toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', '|', 'placeholder' ] - } ) - .then( editor => { - // This code runs after the editor initialization. - // ... - } ) - .catch( error => { - // Error handling if something goes wrong during initialization. - // ... } ); ``` @@ -649,8 +616,8 @@ You can see the placeholder widget implementation in action in the editor below. If you got lost at any point in the tutorial or want to go straight to the solution, there is a repository with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/inline-widget/final-project) available. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/inline-widget/final-project +npx -y degit ckeditor/ckeditor5-tutorials-examples/inline-widget/final-project final-project +cd final-project npm install npm run dev diff --git a/docs/tutorials/widgets/using-react-in-a-widget.md b/docs/tutorials/widgets/using-react-in-a-widget.md index 338238b8172..bf41cd8c15f 100644 --- a/docs/tutorials/widgets/using-react-in-a-widget.md +++ b/docs/tutorials/widgets/using-react-in-a-widget.md @@ -31,19 +31,21 @@ There are a couple of things you should know before you start: ## Let's start -The easiest way to set up your project is to grab the starter files from the [GitHub repository for this tutorial](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/react-widget/starter-files). We gathered all the necessary dependencies there, including some CKEditor 5 packages and other files needed to start the editor. - -The editor has already been created in the `main.js` file with some basic plugins. All you need to do is clone the repository, navigate to the starter-files directory, run the `npm install` command, and you can start coding right away. +The easiest way to get started is to grab the starter project using the commands below. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/react-widget/starter-files +npx -y degit ckeditor/ckeditor5-tutorials-examples/react-widget/starter-files react-widget +cd react-widget npm install npm run dev ``` -You should see a "Hello world" application in your web browser, which might not be much but it is a good start: +This will create a new directory called `react-widget` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server. + +The editor with some basic plugins is created in the `main.js` file. + +Open the URL displayed in your terminal. If everything goes well, you should see a "Hello world" application in your web browser, which might not be much, but it is a good start: {@img assets/img/using-react-in-a-widget-1.png Screenshot of the "Hello world" application in web browser.} @@ -729,8 +731,8 @@ You can see the entire application working below. Click the products in the side If you got lost at any point in the tutorial or want to go straight to the solution, there is a repository with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/react-widget/final-project) available. ```bash -git clone https://github.com/ckeditor/ckeditor5-tutorials-examples -cd ckeditor5-tutorials-examples/react-widget/final-project +npx -y degit ckeditor/ckeditor5-tutorials-examples/react-widget/final-project final-project +cd final-project npm install npm run dev