diff --git a/docs/src/docPages/api/editor.md b/docs/src/docPages/api/editor.md
index 26d312911..a300ee57a 100644
--- a/docs/src/docPages/api/editor.md
+++ b/docs/src/docPages/api/editor.md
@@ -5,37 +5,147 @@
## Introduction
This class is a central building block of tiptap. It does most of the heavy lifting of creating a working [ProseMirror](https://ProseMirror.net/) editor such as creating the [`EditorView`](https://ProseMirror.net/docs/ref/#view.EditorView), setting the initial [`EditorState`](https://ProseMirror.net/docs/ref/#state.Editor_State) and so on.
-## Configuration
-| Setting | Type | Default | Description |
-| ------------------ | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `autofocus` | `Boolean` | `false` | Focus the editor on init. |
-| `content` | `Object|String` | `null` | The editor state object used by Prosemirror. You can also pass HTML to the `content` slot. When used both, the `content` slot will be ignored. |
-| `editable` | `Boolean` | `true` | When set to `false` the editor is read-only. |
-| `editorProps` | `Object` | `{}` | A list of [Prosemirror editorProps](https://prosemirror.net/docs/ref/#view.EditorProps). |
-| `extensions` | `Array` | `[]` | A list of extensions used, by the editor. This can be `Nodes`, `Marks` or `Plugins`. |
-| `parseOptions` | `Object` | `{}` | A list of [Prosemirror parseOptions](https://prosemirror.net/docs/ref/#model.ParseOptions). |
-| `onBlur` | `Function` | `undefined` | Returns an object with the `event` and current `state` and `view` of Prosemirror on blur. |
-| `onFocus` | `Function` | `undefined` | Returns an object with the `event` and current `state` and `view` of Prosemirror on focus. |
-| `onInit` | `Function` | `undefined` | Returns an object with the current `state` and `view` of Prosemirror on init. |
-| `onUpdate` | `Function` | `undefined` | Returns an object with the current `state` of Prosemirror, a `getJSON()` and `getHTML()` function and the `transaction` on every change. |
+## List of available settings
+Check out the API documentation to see [all available options](/api/editor/).
-## Methods
-| Method | Parameters | Description |
-| -------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `getHTML()` | – | Returns the current content as HTML. |
-| `getJSON()` | – | Returns the current content as JSON. |
-| `destroy()` | – | Stops the editor instance and unbinds all events. |
-| `chain()` | - | Create a command chain to call multiple commands at once. |
+### Element
+The `element` specifies the HTML element the editor will be binded too. The following code will add tiptap to an element with the `.element` class:
+
+```js
+import { Editor } from '@tiptap/core'
+import { defaultExtensions } from '@tiptap/starter-kit'
+
+new Editor({
+ element: document.querySelector('.element'),
+ extensions: defaultExtensions(),
+})
+```
+
+### Extensions
+It’s required to pass a list of extensions to the `extensions` property, even if you only want to allow paragraphs.
+
+```js
+import { Editor } from '@tiptap/core'
+import { defaultExtensions } from '@tiptap/starter-kit'
+import Document from '@tiptap/extension-document'
+import Paragraph from '@tiptap/extension-paragraph'
+import Text from '@tiptap/extension-text'
+import Highlight from '@tiptap/extension-highlight'
+
+new Editor({
+ // Use the default extensions
+ extensions: defaultExtensions(),
+
+ // … or use specific extensions
+ extensions: [
+ Document,
+ Paragraph,
+ Text,
+ ],
+
+ // … or both
+ extensions: [
+ ...defaultExtensions(),
+ Highlight,
+ ]
+})
+```
+
+### Content
+With the `content` property you can provide the initial content for the editor. This can be HTML or JSON.
+
+```js
+import { Editor } from '@tiptap/core'
+import { defaultExtensions } from '@tiptap/starter-kit'
+
+new Editor({
+ content: `Example Text
`,
+ extensions: defaultExtensions(),
+})
+```
+
+### Editable
+The `editable` property determines if users can write into the editor.
+
+```js
+import { Editor } from '@tiptap/core'
+import { defaultExtensions } from '@tiptap/starter-kit'
+
+new Editor({
+ content: `Example Text
`,
+ extensions: defaultExtensions(),
+ editable: false,
+})
+```
+
+### Autofocus
+With `autofocus` you can force the cursor to jump in the editor on initialization.
+
+```js
+import { Editor } from '@tiptap/core'
+import { defaultExtensions } from '@tiptap/starter-kit'
+
+new Editor({
+ extensions: defaultExtensions(),
+ autofocus: false,
+})
+```
+
+| Value | Description |
+| --------- | ------------------------------------------------------ |
+| `'start'` | Sets the focus to the beginning of the document. |
+| `'end'` | Sets the focus to the end of the document. |
+| number | Sets the focus to a specific position in the document. |
+| `true` | Enables autofocus. |
+| `false` | Disables autofocus. |
+| `null` | Disables autofocus. |
+
+
+### Inject CSS
+By default, tiptap injects [a little bit of CSS](https://github.com/ueberdosis/tiptap-next/tree/main/packages/core/src/style.ts). With `injectCSS` you can disable that.
+
+```js
+import { Editor } from '@tiptap/core'
+import { defaultExtensions } from '@tiptap/starter-kit'
+
+new Editor({
+ extensions: defaultExtensions(),
+ injectCSS: false,
+})
+```
+
+
+
+## List of available methods
+An editor instance will provide the following public methods. They’ll help you to work with the editor.
+
+Don’t confuse methods with [commands](/api/commands), which are used to change the state of editor (content, selection, and so on) and only return `true` or `false`.
+
+| Method | Parameters | Description |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `can()` | - | Check if a command or a command chain can be executed. Without executing it. |
-| `setOptions()` | `options` A list of options | Update editor options. |
-| `isEditable()` | - | Returns whether the editor is editable. |
-| `state()` | - | Returns the editor state. |
-| `registerCommands()` | `commands` A list of commands | Register a list of commands. |
-| `registerCommand()` | `name` The name of your command
`callback` The method of your command | Register a command. |
-| `registerPlugin()` | `plugin` A ProseMirror plugin
`handlePlugins` Control how to merge the plugin into the existing plugins. | Register a ProseMirror plugin. |
-| `unregisterPlugin()` | `name` The plugins name | Unregister a ProseMirror plugin. |
-| `createDocument()` | `content` EditorContent
`parseOptions` | Creates a ProseMirror document. |
-| `getNodeAttrs()` | `name` Name of the node | Get attributes of the currently selected node. |
-| `getMarkAttrs()` | `name` Name of the mark | Get attributes of the currently selected mark. |
-| `isActive()` | `name` Name of the node or mark
`attrs` Attributes of the node or mark | Returns if the currently selected node or mark is active. |
-| `isEmpty()` | - | Check if there is no content. |
+| `chain()` | - | Create a command chain to call multiple commands at once. |
+| `createDocument()` | `content` EditorContent
`parseOptions` | Creates a ProseMirror document. |
+| `destroy()` | – | Stops the editor instance and unbinds all events. |
+| `getHTML()` | – | Returns the current content as HTML. |
+| `getJSON()` | – | Returns the current content as JSON. |
+| `getMarkAttrs()` | `state` State of the editor
`name` Name of the mark | Get attributes of the currently selected mark. |
+| `getNodeAttrs()` | `state` State of the editor`name` Name of the node | Get attributes of the currently selected node. |
+| `isActive()` | `name` Name of the node or mark
`attrs` Attributes of the node or mark | Returns if the currently selected node or mark is active. |
+| `isEditable()` | - | Returns whether the editor is editable. |
+| `isEmpty()` | - | Check if there is no content. |
+| `registerCommand()` | `name` The name of your command
`callback` The method of your command | Register a command. |
+| `registerCommands()` | `commands` A list of commands | Register a list of commands. |
+| `registerPlugin()` | `plugin` A ProseMirror plugin
`handlePlugins` Control how to merge the plugin into the existing plugins. | Register a ProseMirror plugin. |
+| `setOptions()` | `options` A list of options | Update editor options. |
+| `unregisterPlugin()` | `name` The plugins name | Unregister a ProseMirror plugin. |
diff --git a/docs/src/docPages/guide/configuration.md b/docs/src/docPages/guide/configuration.md
deleted file mode 100644
index c999cadae..000000000
--- a/docs/src/docPages/guide/configuration.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Configuration
-
-## toc
-
-## Introduction
-tiptap is all about customization. There are a ton of options to configure the behavior and functionality of the editor. Most of those settings can be set before creating the Editor. Give tiptap a JSON with all the settings you would like to overwrite.
-
-## Overwrite the default settings
-See an example with `autofocus: true` here:
-
-```js
-import { Editor } from '@tiptap/core'
-import { defaultExtensions } from '@tiptap/starter-kit'
-
-new Editor({
- element: document.querySelector('.element'),
- extensions: defaultExtensions(),
- content: 'Hey there!
',
- autofocus: true,
-})
-```
-
-This will set the focus to tiptap after the editor is initialized. Of course, there are way more options available.
-
-Check out the API documentation to see [all available options](/api/editor/).
diff --git a/docs/src/docPages/guide/configure-the-editor.md b/docs/src/docPages/guide/configure-the-editor.md
new file mode 100644
index 000000000..695a1db79
--- /dev/null
+++ b/docs/src/docPages/guide/configure-the-editor.md
@@ -0,0 +1,63 @@
+# Configure the editor
+
+## toc
+
+## Introduction
+There are a few things you can control when initializing a new editor. For most cases it’s enough to say where tiptap should be rendered (`element`), what functionalities you want to enable (`extensions`) and what the initial document should be (`content`). A few more things can be configured though. Let’s look at a fully configured editor example.
+
+## Configure the editor
+To add your configuration, pass [an object with settings](/api/editor) to the `Editor` class, like shown here:
+
+```js
+import { Editor } from '@tiptap/core'
+import Document from '@tiptap/extension-document'
+import Paragraph from '@tiptap/extension-paragraph'
+import Text from '@tiptap/extension-text'
+
+new Editor({
+ element: document.querySelector('.element'),
+ extensions: [
+ Document,
+ Paragraph,
+ Text,
+ ],
+ content: 'Example Text
',
+ autofocus: true,
+ editable: true,
+ injectCSS: false,
+})
+```
+
+This will do the following:
+
+1. bind tiptap to `.element`,
+2. load the `Document`, `Paragraph` and `Text` extensions,
+3. set the initial content,
+4. place the cursor in the editor after initialization,
+5. make the text editable (but that’s the default anyway), and
+6. disable the loading of [the default CSS](https://github.com/ueberdosis/tiptap-next/tree/main/packages/core/src/style.ts) (which is not much anyway).
+
+## Configure extensions
+A lot of the extension can be configured, too. Add an `.configure()` to the extension and pass an object to it. The following example will disable the default heading levels 4, 5 and 6:
+
+```js
+import { Editor } from '@tiptap/core'
+import Document from '@tiptap/extension-document'
+import Paragraph from '@tiptap/extension-paragraph'
+import Text from '@tiptap/extension-text'
+import Heading from '@tiptap/extension-heading'
+
+new Editor({
+ element: document.querySelector('.element'),
+ extensions: [
+ Document,
+ Paragraph,
+ Text,
+ Heading.configure({
+ level: [1, 2, 3],
+ }),
+ ],
+})
+```
+
+Have a look at the documentation of the extension you’re using to learn more about their settings.
diff --git a/docs/src/docPages/overview/upgrade-guide.md b/docs/src/docPages/overview/upgrade-guide.md
index a29d8c25d..6c24f5ef9 100644
--- a/docs/src/docPages/overview/upgrade-guide.md
+++ b/docs/src/docPages/overview/upgrade-guide.md
@@ -22,6 +22,8 @@ We’re waiting for Gridsome to be compatible with Vue.js 3.
### Explicitly register the Document, Text and Paragraph extensions
tiptap 1 tried to hide a few required extensions from you with the default setting `useBuiltInExtensions: true`. That setting has been removed and you’re required to import all extensions. Be sure to explicitly import at least the [Document](/api/nodes/document), [Paragraph](/api/nodes/paragraph) and [Text](/api/nodes/text) extensions.
+TODO: removed dropCursor, enableDropCursor, enableGapCursor
+
```js
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
@@ -40,6 +42,9 @@ new Editor({
### New document type
~~**We renamed the default `Document` type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name.~~
+### Removed methods
+TODO: state()
+
### New extension API
In case you’ve built some custom extensions for your project, you’re required to rewrite them to fit the new API. No worries, you can keep a lot of your work though. The `schema`, `commands`, `keys`, `inputRules` and `pasteRules` all work like they did before. It’s just different how you register them.
diff --git a/docs/src/links.yaml b/docs/src/links.yaml
index 49d408220..0db1c9ad8 100644
--- a/docs/src/links.yaml
+++ b/docs/src/links.yaml
@@ -45,8 +45,8 @@
link: /guide/getting-started
new: true
- title: Configure the editor
- link: /guide/configuration
- draft: true
+ link: /guide/configure-the-editor
+ new: true
- title: Create a new toolbar
link: /guide/create-your-editor
draft: true