From 3518943e62b60343765e23254c77e413cc206f6e Mon Sep 17 00:00:00 2001
From: Hans Pagel <hans.pagel@ueber.io>
Date: Wed, 28 Oct 2020 16:32:06 +0100
Subject: [PATCH] update content

---
 docs/src/demos/Examples/Links/index.vue       |  10 +-
 docs/src/docPages/api/keyboard-shortcuts.md   | 130 +++++++-------
 .../docPages/guide/build-custom-extensions.md | 161 ++++++++++++++++++
 ...d-your-editor.md => create-your-editor.md} |   0
 docs/src/docPages/guide/custom-extensions.md  | 142 ---------------
 docs/src/docPages/guide/custom-styling.md     |  26 ++-
 docs/src/docPages/overview/upgrade-guide.md   |  66 +++----
 docs/src/links.yaml                           |   8 +-
 packages/extension-blockquote/index.ts        |   2 +-
 9 files changed, 288 insertions(+), 257 deletions(-)
 create mode 100644 docs/src/docPages/guide/build-custom-extensions.md
 rename docs/src/docPages/guide/{build-your-editor.md => create-your-editor.md} (100%)
 delete mode 100644 docs/src/docPages/guide/custom-extensions.md

diff --git a/docs/src/demos/Examples/Links/index.vue b/docs/src/demos/Examples/Links/index.vue
index e3240fc7..0bdfe621 100644
--- a/docs/src/demos/Examples/Links/index.vue
+++ b/docs/src/demos/Examples/Links/index.vue
@@ -11,13 +11,19 @@
 </template>
 
 <script>
-import { Editor } from '@tiptap/core'
+import { Editor, mergeAttributes } from '@tiptap/core'
 import { EditorContent } from '@tiptap/vue'
 import Document from '@tiptap/extension-document'
 import Paragraph from '@tiptap/extension-paragraph'
 import Text from '@tiptap/extension-text'
 import Link from '@tiptap/extension-link'
 
+const CustomLink = Link.extend({
+  renderHTML({ attributes }) {
+    return ['strong', mergeAttributes(attributes, { rel: this.options.rel }), 0]
+  },
+})
+
 export default {
   components: {
     EditorContent,
@@ -35,7 +41,7 @@ export default {
         Document(),
         Paragraph(),
         Text(),
-        Link(),
+        CustomLink(),
       ],
       content: `
         <p>
diff --git a/docs/src/docPages/api/keyboard-shortcuts.md b/docs/src/docPages/api/keyboard-shortcuts.md
index bb0eee9b..ef795cb0 100644
--- a/docs/src/docPages/api/keyboard-shortcuts.md
+++ b/docs/src/docPages/api/keyboard-shortcuts.md
@@ -3,77 +3,49 @@
 ## toc
 
 ## Introduction
-Keyboard shortcuts may be strings like `'Shift-Control-Enter'`. Keys are based on the strings that can appear in `event.key`, concatenated with a `-`. There is a little tool called [keycode.info](https://keycode.info/), which shows the `event.key` interactively.
-
-Use lowercase letters to refer to letter keys (or uppercase letters if you want shift to be held). You may use `Space` as an alias for the <code>&nbsp;</code>.
-
-Modifiers can be given in any order. `Shift`, `Alt`, `Control` and `Cmd` are recognized. For characters that are created by holding shift, the `Shift` prefix is implied, and should not be added explicitly.
-
-You can use `Mod` as a shorthand for `Cmd` on Mac and `Control` on other platforms.
-
-## Overwrite keyboard shortcuts
-
-```js
-// 1. Import the extension
-import BulletList from '@tiptap/extension-bullet-list'
-
-// 2. Overwrite the keyboard shortcuts
-const CustomBulletList = BulletList()
-  .keys(({ editor }) => ({
-    // ↓ your new keyboard shortcut
-    'Mod-l': () => editor.bulletList(),
-  }))
-  .create() // Don’t forget that!
-
-// 3. Add the custom extension to your editor
-new Editor({
-  extensions: [
-      CustomBulletList(),
-      // …
-  ]
-})
-```
+Tiptap comes with sensible keyboard shortcut defaults. Depending on what you want to use it for, you’ll probably want to change those keyboard shortcuts to your liking. Let’s have a look at what we defined for you, and show you how to change it then!
 
 ## Predefined keyboard shortcuts
+Most of the core extensions register their own keyboard shortcuts. Depending on what set of extension you use, not all of the below listed keyboard shortcuts work for your editor.
 
 ### Essentials
-| Action                   | Windows/Linux         | macOS             |
-| ------------------------ | --------------------- | ----------------- |
-| Copy                     | `Control`&nbsp;`C`         | `Cmd`&nbsp;`C`         |
-| Cut                      | `Control`&nbsp;`X`         | `Cmd`&nbsp;`X`         |
-| Paste                    | `Control`&nbsp;`V`         | `Cmd`&nbsp;`V`         |
+| Action                   | Windows/Linux                   | macOS                       |
+| ------------------------ | ------------------------------- | --------------------------- |
+| Copy                     | `Control`&nbsp;`C`              | `Cmd`&nbsp;`C`              |
+| Cut                      | `Control`&nbsp;`X`              | `Cmd`&nbsp;`X`              |
+| Paste                    | `Control`&nbsp;`V`              | `Cmd`&nbsp;`V`              |
 | Paste without formatting | `Control`&nbsp;`Shift`&nbsp;`V` | `Cmd`&nbsp;`Shift`&nbsp;`V` |
-| Undo                     | `Control`&nbsp;`Z`         | `Cmd`&nbsp;`Z`         |
+| Undo                     | `Control`&nbsp;`Z`              | `Cmd`&nbsp;`Z`              |
 | Redo                     | `Control`&nbsp;`Shift`&nbsp;`Z` | `Cmd`&nbsp;`Shift`&nbsp;`Z` |
-| Insert or edit link      | `Control`&nbsp;`K`         | `Cmd`&nbsp;`K`         |
-| Open link                | `Alt`&nbsp;`Enter`         | `Alt`&nbsp;`Enter`     |
-| Find                     | `Control`&nbsp;`F`         | `Cmd`&nbsp;`F`         |
-| Find and replace         | `Control`&nbsp;`H`         | `Cmd`&nbsp;`Shift`&nbsp;`H` |
-| Find again               | `Control`&nbsp;`G`         | `Cmd`&nbsp;`G`         |
+| Insert or edit link      | `Control`&nbsp;`K`              | `Cmd`&nbsp;`K`              |
+| Open link                | `Alt`&nbsp;`Enter`              | `Alt`&nbsp;`Enter`          |
+| Find                     | `Control`&nbsp;`F`              | `Cmd`&nbsp;`F`              |
+| Find and replace         | `Control`&nbsp;`H`              | `Cmd`&nbsp;`Shift`&nbsp;`H` |
+| Find again               | `Control`&nbsp;`G`              | `Cmd`&nbsp;`G`              |
 | Find previous            | `Control`&nbsp;`Shift`&nbsp;`G` | `Cmd`&nbsp;`Shift`&nbsp;`G` |
-| Repeat last action       | `Control`&nbsp;`Y`         | `Cmd`&nbsp;`Y`         |
-| Add a line break         | `Shift`&nbsp;`Enter`       | `Shift`&nbsp;`Enter`   |
+| Repeat last action       | `Control`&nbsp;`Y`              | `Cmd`&nbsp;`Y`              |
+| Add a line break         | `Shift`&nbsp;`Enter`            | `Shift`&nbsp;`Enter`        |
 
 ### Text Formatting
-| Action                | Windows/Linux                                 | macOS             |
-| --------------------- | --------------------------------------------- | ----------------- |
-| Bold                  | `Control`&nbsp;`B`                                 | `Cmd`&nbsp;`B`         |
-| Italicize             | `Control`&nbsp;`I`                                 | `Cmd`&nbsp;`I`         |
-| Underline             | `Control`&nbsp;`U`                                 | `Cmd`&nbsp;`U`         |
+| Action                | Windows/Linux                                           | macOS                       |
+| --------------------- | ------------------------------------------------------- | --------------------------- |
+| Bold                  | `Control`&nbsp;`B`                                      | `Cmd`&nbsp;`B`              |
+| Italicize             | `Control`&nbsp;`I`                                      | `Cmd`&nbsp;`I`              |
+| Underline             | `Control`&nbsp;`U`                                      | `Cmd`&nbsp;`U`              |
 | Strikethrough         | `Alt`&nbsp;`Shift`&nbsp;`5`                             | `Cmd`&nbsp;`Shift`&nbsp;`X` |
-| Superscript           | `Control`&nbsp;`.`                                 | `Cmd`&nbsp;`.`         |
-| Subscript             | `Control`&nbsp;`,`                                 | `Cmd`&nbsp;`,`         |
+| Superscript           | `Control`&nbsp;`.`                                      | `Cmd`&nbsp;`.`              |
+| Subscript             | `Control`&nbsp;`,`                                      | `Cmd`&nbsp;`,`              |
 | Copy text formatting  | `Control`&nbsp;`Alt`&nbsp;`C`                           | `Cmd`&nbsp;`Alt`&nbsp;`C`   |
 | Paste text formatting | `Control`&nbsp;`Alt`&nbsp;`V`                           | `Cmd`&nbsp;`Alt`&nbsp;`V`   |
-| Clear text formatting | `Control`&nbsp;<code>\</code><br>`Control`&nbsp;`Space` | `Cmd`&nbsp;`\`         |
+| Clear text formatting | `Control`&nbsp;<code>\</code><br>`Control`&nbsp;`Space` | `Cmd`&nbsp;`\`              |
 | Increase font size    | `Control`&nbsp;`Shift`&nbsp;`>`                         | `Cmd`&nbsp;`Shift`&nbsp;`>` |
 | Decrease font size    | `Control`&nbsp;`Shift`&nbsp;`<`                         | `Cmd`&nbsp;`Shift`&nbsp;`<` |
 
 ### Paragraph Formatting
-| Action                         | Windows/Linux         | macOS                 |
-| ------------------------------ | --------------------- | --------------------- |
-| Increase paragraph indentation | `Control`&nbsp;`]`         | `Cmd`&nbsp;`]`             |
-| Decrease paragraph indentation | `Control`&nbsp;`[`         | `Cmd`&nbsp;`[`             |
+| Action                         | Windows/Linux                   | macOS                           |
+| ------------------------------ | ------------------------------- | ------------------------------- |
+| Increase paragraph indentation | `Control`&nbsp;`]`              | `Cmd`&nbsp;`]`                  |
+| Decrease paragraph indentation | `Control`&nbsp;`[`              | `Cmd`&nbsp;`[`                  |
 | Apply normal text style        | `Control`&nbsp;`Alt`&nbsp;`0`   | `Cmd`&nbsp;`Alt`&nbsp;`0`       |
 | Apply heading style 1          | `Control`&nbsp;`Alt`&nbsp;`1`   | `Cmd`&nbsp;`Alt`&nbsp;`1`       |
 | Apply heading style 2          | `Control`&nbsp;`Alt`&nbsp;`2`   | `Cmd`&nbsp;`Alt`&nbsp;`2`       |
@@ -91,14 +63,48 @@ new Editor({
 | Move paragraph down            | `Control`&nbsp;`Shift`&nbsp;`↓` | `Control`&nbsp;`Shift`&nbsp;`↓` |
 
 ### Text Selection
-| Action                                            | Windows/Linux         | macOS             |
-| ------------------------------------------------- | --------------------- | ----------------- |
-| Select all                                        | `Control`&nbsp;`A`         | `Cmd`&nbsp;`A`         |
-| Extend selection one character to left            | `Shift`&nbsp;`←`           | `Shift`&nbsp;`←`       |
-| Extend selection one character to right           | `Shift`&nbsp;`→`           | `Shift`&nbsp;`→`       |
-| Extend selection one line up                      | `Shift`&nbsp;`↑`           | `Shift`&nbsp;`↑`       |
-| Extend selection one line down                    | `Shift`&nbsp;`↓`           | `Shift`&nbsp;`↓`       |
+| Action                                            | Windows/Linux                   | macOS                       |
+| ------------------------------------------------- | ------------------------------- | --------------------------- |
+| Select all                                        | `Control`&nbsp;`A`              | `Cmd`&nbsp;`A`              |
+| Extend selection one character to left            | `Shift`&nbsp;`←`                | `Shift`&nbsp;`←`            |
+| Extend selection one character to right           | `Shift`&nbsp;`→`                | `Shift`&nbsp;`→`            |
+| Extend selection one line up                      | `Shift`&nbsp;`↑`                | `Shift`&nbsp;`↑`            |
+| Extend selection one line down                    | `Shift`&nbsp;`↓`                | `Shift`&nbsp;`↓`            |
 | Extend selection one paragraph up                 | `Alt`&nbsp;`Shift`&nbsp;`↑`     | `Alt`&nbsp;`Shift`&nbsp;`↑` |
 | Extend selection one paragraph down               | `Alt`&nbsp;`Shift`&nbsp;`↓`     | `Alt`&nbsp;`Shift`&nbsp;`↓` |
 | Extend selection to the beginning of the document | `Control`&nbsp;`Shift`&nbsp;`↑` | `Cmd`&nbsp;`Shift`&nbsp;`↑` |
 | Extend selection to the end of the document       | `Control`&nbsp;`Shift`&nbsp;`↓` | `Cmd`&nbsp;`Shift`&nbsp;`↓` |
+
+## Overwrite keyboard shortcuts
+Keyboard shortcuts may be strings like `'Shift-Control-Enter'`. Keys are based on the strings that can appear in `event.key`, concatenated with a `-`. There is a little tool called [keycode.info](https://keycode.info/), which shows the `event.key` interactively.
+
+Use lowercase letters to refer to letter keys (or uppercase letters if you want shift to be held). You may use `Space` as an alias for the <code>&nbsp;</code>.
+
+Modifiers can be given in any order. `Shift`, `Alt`, `Control` and `Cmd` are recognized. For characters that are created by holding shift, the `Shift` prefix is implied, and should not be added explicitly.
+
+You can use `Mod` as a shorthand for `Cmd` on Mac and `Control` on other platforms.
+
+Here is an example how you can overwrite the keyboard shortcuts for an existing extension:
+
+```js
+// 1. Import the extension
+import BulletList from '@tiptap/extension-bullet-list'
+
+// 2. Overwrite the keyboard shortcuts
+const CustomBulletList = BulletList.extend({
+  addKeyboardShortcuts() {
+    return {
+      // ↓ your new keyboard shortcut
+      'Mod-l': () => this.editor.bulletList(),
+    }
+  },
+})
+
+// 3. Add the custom extension to your editor
+new Editor({
+  extensions: [
+    CustomBulletList(),
+    // …
+  ]
+})
+```
diff --git a/docs/src/docPages/guide/build-custom-extensions.md b/docs/src/docPages/guide/build-custom-extensions.md
new file mode 100644
index 00000000..46716c45
--- /dev/null
+++ b/docs/src/docPages/guide/build-custom-extensions.md
@@ -0,0 +1,161 @@
+# Build custom extensions
+
+## toc
+
+## Introduction
+One of the strength of tiptap is it’s extendability. You don’t depend on the provided extensions, it’s intended to extend the editor to your liking. With custom extensions you can add new content types and new functionalities, on top of what already exists or starting from scratch.
+
+## Option 1: Extend existing extensions
+Let’s say you want to change the keyboard shortcuts for the bullet list. You should start by looking at [the source code of the `BulletList` extension](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/index.ts) and find the part you would like to change. In that case, the keyboard shortcut, and just that.
+
+Every extension has an `extend()` method, which takes an object with everything you want to change or add to it. For the bespoken example, your code could like that:
+
+```js
+// 1. Import the extension
+import BulletList from '@tiptap/extension-bullet-list'
+
+// 2. Overwrite the keyboard shortcuts
+const CustomBulletList = BulletList.extend({
+  addKeyboardShortcuts() {
+    return {
+      'Mod-l': () => this.editor.bulletList(),
+    }
+  },
+})
+
+// 3. Add the custom extension to your editor
+new Editor({
+  extensions: [
+    CustomBulletList(),
+    // …
+  ]
+})
+```
+
+The same applies to every aspect of an existing extension, except to the name. Let’s look at all the things that you can change through the extend method. We focus on one aspect in every example, but you can combine all those examples and change multiple aspects in one `extend()` call too.
+
+### Name
+The extension name is used in a whole lot of places and changing it isn’t too easy. If you want to change the name of an extension, it’s recommended to copy the whole extension and change the name in all occurrences.
+
+The extension name is also part of the JSON. If you [store your content as JSON](http://localhost:3000/guide/store-content#option-1-json), you need to change the name in there too.
+
+### Settings
+
+All settings can be overwritten through the extension anyway, but if you want to change the defaults, for example to provide a library on top of tiptap for other developers, you can do it like that:
+
+```js
+import Heading from '@tiptap/extension-heading'
+
+const CustomHeading = Heading.extend({
+  defaultOptions: {
+    levels: [1, 2, 3],
+  },
+})
+```
+
+### Schema
+
+Tiptap works with a [strict schema](/api/schema), which configures how the content can be structured, nested, how it behaves and many more things. You can change all aspects of the schema for existing extensions. Let’s walk through a few common use cases.
+
+The default `Blockquote` extension can wrap other nodes, like headings. If you want to allow nothing but paragraphs in your blockquotes, this is how you could achieve it:
+
+```js
+// blockquotes include paragraphs only
+import Blockquote from '@tiptap/extension-blockquote'
+
+const CustomBlockquote = Blockquote.extend({
+  content: 'paragraph block*',
+})
+```
+
+The schema even allows to make your nodes draggable, that’s what the `draggable` option is for, which defaults to `false`. Here is an example for draggable paragraphs:
+
+```js
+// draggable paragraphs
+import Paragraph from '@tiptap/extension-paragraph'
+
+const CustomParagraph = Paragraph.extend({
+  draggable: true,
+})
+```
+
+### Commands
+
+```js
+import Paragraph from '@tiptap/extension-paragraph'
+
+const CustomParagraph = Paragraph.extend({
+  addCommands() {
+    return {
+      paragraph: () => ({ commands }) => {
+        return commands.toggleBlockType('paragraph', 'paragraph')
+      },
+    }
+  },
+})
+```
+
+### Keyboard shortcuts
+Most core extensions come with sensible keyboard shortcut defaults. Depending on what you want to build, you’ll likely want to change them though. With the `addKeyboardShortcuts()` method you can overwrite the predefined shortcut map:
+
+```js
+// change the bullet list keyboard shortcut
+import BulletList from '@tiptap/extension-bullet-list'
+
+const CustomBulletList = BulletList.extend({
+  addKeyboardShortcuts() {
+    return {
+      'Mod-l': () => this.editor.bulletList(),
+    }
+  },
+})
+```
+
+### Input rules
+
+```js
+// use the ~single tilde~ markdown shortcut
+import Strike from '@tiptap/extension-strike'
+import { markInputRule } from '@tiptap/core'
+
+const inputRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/gm
+
+const CustomStrike = Strike.extend({
+  addInputRules() {
+    return [
+      markInputRule(inputRegex, this.type),
+    ]
+  },
+})
+```
+
+### Paste rules
+
+```js
+// overwrite the underline regex for pasted text
+import Underline from '@tiptap/extension-underline'
+import { markPasteRule } from '@tiptap/core'
+
+const pasteRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/gm
+
+const CustomUnderline = Underline.extend({
+  addPasteRules() {
+    return [
+      markPasteRule(inputRegex, this.type),
+    ]
+  },
+})
+```
+
+## Option 2: Start from scratch
+
+### Read the documentation
+Although tiptap tries to hide most of the complexity of ProseMirror, it’s built on top of its APIs and we recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/) for advanced usage. You’ll have a better understanding of how everything works under the hood and get more familiar with many terms and jargon used by tiptap.
+
+### Have a look at existing extensions
+
+### Get started
+
+### Ask questions
+
+### Share your extension
diff --git a/docs/src/docPages/guide/build-your-editor.md b/docs/src/docPages/guide/create-your-editor.md
similarity index 100%
rename from docs/src/docPages/guide/build-your-editor.md
rename to docs/src/docPages/guide/create-your-editor.md
diff --git a/docs/src/docPages/guide/custom-extensions.md b/docs/src/docPages/guide/custom-extensions.md
deleted file mode 100644
index d03ede31..00000000
--- a/docs/src/docPages/guide/custom-extensions.md
+++ /dev/null
@@ -1,142 +0,0 @@
-# Custom extensions
-
-## toc
-
-## Introduction
-One of the strength of tiptap is it’s extendability. You don’t depend on the provided extensions, it’s intended to extend the editor to your liking. With custom extensions you can add new content types and new functionalities, on top of what already exists or on top of that.
-
-## Option 1: Change defaults
-
-Let’s say you want to change the keyboard shortcuts for the bullet list. You should start by looking at [the source code of the `BulletList` extension](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/index.ts) and find the default you’d like to change. In that case, the keyboard shortcut, and just that.
-
-```js
-// 1. Import the extension
-import BulletList from '@tiptap/extension-bullet-list'
-
-// 2. Overwrite the keyboard shortcuts
-const CustomBulletList = BulletList()
-  .keys(({ editor }) => ({
-    'Mod-l': () => editor.bulletList(),
-  }))
-  .create() // Don’t forget that!
-
-// 3. Add the custom extension to your editor
-new Editor({
-  extensions: [
-      CustomBulletList(),
-      // …
-  ]
-})
-```
-
-You can overwrite every aspect of an existing extension:
-
-### Name
-
-```js
-import Document from '@tiptap/extension-document'
-
-const CustomDocument = Document()
-  .name('doc')
-  .create()
-```
-
-### Settings
-
-```js
-import Heading from '@tiptap/extension-heading'
-
-const CustomHeading = Heading()
-  .defaults({
-    levels: [1, 2, 3],
-    class: 'my-custom-heading',
-  })
-  .create()
-```
-
-### Schema
-
-```js
-import Code from '@tiptap/extension-code'
-
-const CustomCode = Code()
-  .schema(() => ({
-    excludes: '_',
-    parseDOM: [
-      { tag: 'code' },
-    ],
-    toDOM: () => ['code', { 'data-attribute': 'foobar' }, 0],
-  }))
-  .create()
-```
-
-### Commands
-
-```js
-import Paragraph from '@tiptap/extension-paragraph'
-
-const CustomParagraph = Paragraph()
-  .commands(() => ({
-    paragraph: () => ({ commands }) => {
-      return commands.toggleBlockType(name, 'paragraph')
-    },
-  }))
-  .create()
-```
-
-### Keyboard shortcuts
-
-```js
-import BulletList from '@tiptap/extension-bullet-list'
-
-const CustomBulletList = BulletList()
-  .keys(({ editor }) => ({
-    'Mod-l': () => editor.bulletList(),
-  }))
-  .create()
-```
-
-### Input rules
-
-```js
-import Strike from '@tiptap/extension-strike'
-import { markInputRule } from '@tiptap/core'
-
-const inputRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/gm
-
-const CustomStrike = Strike()
-  .inputRules(({ type }) => [
-    markInputRule(inputRegex, type),
-  ])
-  .create()
-```
-
-### Paste rules
-
-```js
-import Underline from '@tiptap/extension-underline'
-import { markPasteRule } from '@tiptap/core'
-
-const pasteRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/gm
-
-const CustomUnderline = Underline()
-  .pasteRules(({ type }) => [
-    markPasteRule(pasteRegex, type),
-  ])
-  .create()
-```
-
-## Option 2: Extend existing extensions
-
-## Option 3: Start from scratch
-
-### 1. Read the documentation
-Although tiptap tries to hide most of the complexity of ProseMirror, it’s built on top of its APIs and we recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/) for advanced usage. You’ll have a better understanding of how everything works under the hood and get more familiar with many terms and jargon used by tiptap.
-
-### 2. Have a look at existing extensions
-
-### 3. Get started
-
-### 4. Ask questions
-
-### 5. Publish a community extension
diff --git a/docs/src/docPages/guide/custom-styling.md b/docs/src/docPages/guide/custom-styling.md
index 0a759ae4..596cb451 100644
--- a/docs/src/docPages/guide/custom-styling.md
+++ b/docs/src/docPages/guide/custom-styling.md
@@ -28,15 +28,21 @@ p {
 ## Option 2: Add custom classes
 Most extensions have a `class` option, which you can use to add a custom CSS class to the HTML tag.
 
+Most extensions allow you to add attributes to the rendered HTML through the `attributes` configuration. You can use that to add a custom class (or any other attribute):
+
 ```js
 new Editor({
   extensions: [
     Document(),
     Paragraph({
-      class: 'my-custom-paragraph',
+      attributes: {
+        class: 'my-custom-paragraph',
+      },
     }),
     Heading({
-      class: 'my-custom-heading',
+      attributes: {
+        class: 'my-custom-heading',
+      },
     }),
     Text(),
   ]
@@ -50,17 +56,21 @@ The rendered HTML will look like that:
 <p class="my-custom-paragraph">Wow, that’s really custom.</p>
 ```
 
+If there are already classes defined by the extensions, your classes will be added.
+
 ## Option 3: Customize the HTML
 You can even customize the markup for every extension. This will make a custom bold extension that doesn’t render a `<strong>` tag, but a `<b>` tag:
 
 ```js
 import Bold from '@tiptap/extension-bold'
 
-const CustomBold = Bold
-  .schema(() => ({
-    toDOM: () => ['b', 0],
-  }))
-  .create()
+const CustomBold = Bold.extend({
+  renderHTML({ attributes }) {
+    // Original:
+    // return ['strong', attributes, 0]
+    return ['b', attributes, 0]
+  },
+})
 
 new Editor({
   extensions: [
@@ -70,4 +80,4 @@ new Editor({
 })
 ```
 
-You should put your custom extensions in separate files though, but I think you’ve got the idea.
+You should put your custom extensions in separate files though, but I think you got the idea.
diff --git a/docs/src/docPages/overview/upgrade-guide.md b/docs/src/docPages/overview/upgrade-guide.md
index 4bdf8d08..c6382864 100644
--- a/docs/src/docPages/overview/upgrade-guide.md
+++ b/docs/src/docPages/overview/upgrade-guide.md
@@ -36,48 +36,39 @@ 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.
-
-```js
-import Document from '@tiptap/extension-document'
-
-const CustomDocument = Document.name('doc').create()
-
-new Editor({
-  extensions: [
-    CustomDocument(),
-    // …
-  ]
-})
-```
+~~**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.~~
 
 ### 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.
 
 ```js
-import { Node } from '@tiptap/core'
+import { createNode } from '@tiptap/core'
 
-const CustomExtension = new Node()
-  .name('custom_extension')
-  .defaults({
-    // …
-  })
-  .schema(() => ({
-    // …
-  }))
-  .commands(({ editor, name }) => ({
-    // …
-  }))
-  .keys(({ editor }) => ({
-    // …
-  }))
-  .inputRules(({ type }) => [
-    // …
-  ])
-  .pasteRules(({ type }) => [
-    // …
-  ])
-  .create()
+const CustomExtension = createNode({
+  name: 'custom_extension'
+  defaultOptions: {
+    …
+  },
+  addAttributes() {
+    …
+  },
+  parseHTML() {
+    …
+  },
+  renderHTML({ node, attributes }) {
+    …
+  },
+  addCommands() {
+    …
+  },
+  addKeyboardShortcuts() {
+    …
+  },
+  addInputRules() {
+    …
+  },
+  // and more …
+})
 ```
 
 Don’t forget to call `create()` in the end! Read more about [all the nifty details building custom extensions](/guide/custom-extensions) in our guide.
@@ -87,8 +78,7 @@ Don’t forget to call `create()` in the end! Read more about [all the nifty det
 
 | Old method name | New method name |
 | --------------- | --------------- |
-| ~~`getHTML`~~   | `html`          |
-| ~~`getJSON`~~   | `json`          |
+| ~~`…`~~         | `…`             |
 
 ### Commands can be chained now
 
diff --git a/docs/src/links.yaml b/docs/src/links.yaml
index 7ca0c43c..33b15554 100644
--- a/docs/src/links.yaml
+++ b/docs/src/links.yaml
@@ -78,15 +78,15 @@
       link: /guide/getting-started
     - title: Configuration
       link: /guide/configuration
-    - title: Build your editor
-      link: /guide/build-your-editor
+    - title: Create your editor
+      link: /guide/create-your-editor
       draft: true
     - title: Custom styling
       link: /guide/custom-styling
     - title: Store content
       link: /guide/store-content
-    - title: Custom extensions
-      link: /guide/custom-extensions
+    - title: Build custom extensions
+      link: /guide/build-custom-extensions
     # - title: Use Vue Components
     #   link: /guide/use-vue-components
     #   draft: true
diff --git a/packages/extension-blockquote/index.ts b/packages/extension-blockquote/index.ts
index dc6d5a01..bd36fee8 100644
--- a/packages/extension-blockquote/index.ts
+++ b/packages/extension-blockquote/index.ts
@@ -6,7 +6,7 @@ export const inputRegex = /^\s*>\s$/gm
 const Blockquote = createNode({
   name: 'blockquote',
 
-  content: 'block*',
+  content: 'paragraph block*',
 
   group: 'block',