From 0c06ece8e90965357c57bba6f82d48683c4c7dde Mon Sep 17 00:00:00 2001
From: Hans Pagel <hans.pagel@ueber.io>
Date: Tue, 4 May 2021 23:26:07 +0200
Subject: [PATCH] docs: update content

---
 docs/src/docPages/api/extensions.md          | 15 -----
 docs/src/docPages/guide/custom-extensions.md | 14 ++++-
 docs/src/docPages/guide/extend-extensions.md | 62 ++++++++++++++++++++
 3 files changed, 73 insertions(+), 18 deletions(-)

diff --git a/docs/src/docPages/api/extensions.md b/docs/src/docPages/api/extensions.md
index 00869968..f667f936 100644
--- a/docs/src/docPages/api/extensions.md
+++ b/docs/src/docPages/api/extensions.md
@@ -56,18 +56,3 @@ const editor = new Editor({
 
 Learn [more about custom extensions in our guide](/guide/extend-extensions).
 
-### ProseMirror plugins
-ProseMirror has a fantastic eco system with many amazing plugins. If you want to use one of them, you can register them with tiptap like that:
-
-```js
-import { history } from 'prosemirror-history'
-
-const History = Extension.create({
-  addProseMirrorPlugins() {
-    return [
-      history(),
-      // …
-    ]
-  },
-})
-```
diff --git a/docs/src/docPages/guide/custom-extensions.md b/docs/src/docPages/guide/custom-extensions.md
index 0ef601e0..1f4cf87e 100644
--- a/docs/src/docPages/guide/custom-extensions.md
+++ b/docs/src/docPages/guide/custom-extensions.md
@@ -3,16 +3,17 @@
 ## toc
 
 ## Introduction
-You can build your own extensions from scratch with the `Node`, `Mark`, and `Extension` classes. Just pass an object with your configuration and custom code. Read the [overwrite & extend](/guide/extend-extensions) guide to learn more about all the things you can control.
+You can build your own extensions from scratch. Extend the provided `Node`, `Mark`, and `Extension` classes and pass an object with your configuration and custom code.
 
-And if everything is working fine, don’t forget to [share it with the community](https://github.com/ueberdosis/tiptap/issues/819).
+Read the [overwrite & extend](/guide/extend-extensions) guide to learn more about all the things you can control.
 
 ### Create a node
-
 ```js
 import { Node } from '@tiptap/core'
 
 const CustomNode = Node.create({
+  name: 'customNode',
+
   // Your code goes here.
 })
 ```
@@ -22,6 +23,8 @@ const CustomNode = Node.create({
 import { Mark } from '@tiptap/core'
 
 const CustomMark = Mark.create({
+  name: 'customMark',
+
   // Your code goes here.
 })
 ```
@@ -31,6 +34,11 @@ const CustomMark = Mark.create({
 import { Extension } from '@tiptap/core'
 
 const CustomExtension = Extension.create({
+  name: 'customExtension',
+
   // Your code goes here.
 })
 ```
+
+## Sharing
+When everything is working fine, don’t forget to [share it with the community](https://github.com/ueberdosis/tiptap/issues/819).
diff --git a/docs/src/docPages/guide/extend-extensions.md b/docs/src/docPages/guide/extend-extensions.md
index 5dd00900..93d12b14 100644
--- a/docs/src/docPages/guide/extend-extensions.md
+++ b/docs/src/docPages/guide/extend-extensions.md
@@ -178,6 +178,22 @@ const CustomParagraph = Paragraph.extend({
 
 You can disable the rendering of attributes, if you pass `rendered: false`.
 
+#### Extend existing attributes
+If you want to add an attribute to an extension and keep existing attributes, you can access them through `this.parent()`. In some cases, it is undefined, so make sure to check for that case, or use optional chaining `this.parent?.()`
+
+```js
+const CustomTableCell = TableCell.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      myCustomAttribute: {
+        // …
+      },
+    }
+  },
+})
+```
+
 ### Global Attributes
 Attributes can be applied to multiple extensions at once. That’s useful for text alignment, line height, color, font family, and other styling related attributes.
 
@@ -402,6 +418,52 @@ const CustomExtension = Extension.create({
 })
 ```
 
+### ProseMirror Plugins (Advanced)
+After all, tiptap is built on ProseMirror and ProseMirror has a pretty powerful plugin API, too. To access that directly, use `addProseMirrorPlugins()`.
+
+#### Existing plugins
+You can wrap existing ProseMirror plugins in tiptap extensions like shown in the example below.
+
+```js
+import { history } from 'prosemirror-history'
+
+const History = Extension.create({
+  addProseMirrorPlugins() {
+    return [
+      history(),
+      // …
+    ]
+  },
+})
+```
+
+#### Access the ProseMirror API
+To hook into events, for example a click, double click or when content is pasted, you can pass event handlers as `editorProps` to the [editor](/api/editor). Or you can add them to a tiptap extension like shown in the below example.
+
+```js
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from 'prosemirror-state'
+
+export const EventHandler = Extension.create({
+  name: 'eventHandler',
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: new PluginKey('eventHandler'),
+        props: {
+          handleClick(view, pos, event) { /* … */ },
+          handleDoubleClick(view, pos, event) { /* … */ },
+          handlePaste(view, event, slice) { /* … */ },
+          // … and many, many more.
+          // Here is the full list: https://prosemirror.net/docs/ref/#view.EditorProps
+        },
+      }),
+    ]
+  },
+})
+```
+
 ### Node views (Advanced)
 For advanced use cases, where you need to execute JavaScript inside your nodes, for example to render a sophisticated link preview, you need to learn about node views.