From cbe8e1f357fa94eb5a298637715e9ce1d2c483ce Mon Sep 17 00:00:00 2001
From: Hans Pagel <hans.pagel@ueber.io>
Date: Thu, 20 Aug 2020 15:33:16 +0200
Subject: [PATCH] improve the extensions documentation

---
 docs/src/docPages/api/extensions/blockquote.md | 12 ++++++------
 docs/src/docPages/api/extensions/bold.md       | 14 +++++++-------
 docs/src/docPages/api/extensions/bulletlist.md | 14 +++++++-------
 docs/src/docPages/api/extensions/code.md       | 12 ++++++------
 docs/src/docPages/api/extensions/codeblock.md  | 18 +-----------------
 .../api/extensions/codeblockheighlight.md      |  2 ++
 .../docPages/api/extensions/collaboration.md   |  2 ++
 docs/src/docPages/api/extensions/hardbreak.md  |  9 +++++++++
 docs/src/docPages/api/extensions/heading.md    | 12 ++++++------
 docs/src/docPages/api/extensions/history.md    |  8 ++++----
 .../docPages/api/extensions/horizontalrule.md  | 12 ++++++------
 docs/src/docPages/api/extensions/italic.md     | 12 ++++++------
 docs/src/docPages/api/extensions/link.md       |  4 ++--
 docs/src/docPages/api/extensions/listitem.md   |  2 +-
 docs/src/docPages/api/extensions/mention.md    |  2 +-
 .../src/docPages/api/extensions/orderedlist.md | 12 ++++++------
 .../src/docPages/api/extensions/placeholder.md | 12 ++++++------
 docs/src/docPages/api/extensions/strike.md     | 12 ++++++------
 docs/src/docPages/api/extensions/tablecell.md  |  2 +-
 .../src/docPages/api/extensions/tableheader.md |  2 +-
 docs/src/docPages/api/extensions/tablerow.md   |  2 +-
 docs/src/docPages/api/extensions/todoitem.md   |  6 +++---
 docs/src/docPages/api/extensions/todolist.md   | 10 +++++-----
 docs/src/docPages/api/extensions/underline.md  | 12 ++++++------
 docs/src/docPages/api/schema.md                |  2 +-
 docs/src/links.yaml                            |  6 ++++++
 26 files changed, 108 insertions(+), 105 deletions(-)
 create mode 100644 docs/src/docPages/api/extensions/codeblockheighlight.md
 create mode 100644 docs/src/docPages/api/extensions/collaboration.md
 create mode 100644 docs/src/docPages/api/extensions/hardbreak.md

diff --git a/docs/src/docPages/api/extensions/blockquote.md b/docs/src/docPages/api/extensions/blockquote.md
index f759b145..b95265be 100644
--- a/docs/src/docPages/api/extensions/blockquote.md
+++ b/docs/src/docPages/api/extensions/blockquote.md
@@ -1,18 +1,18 @@
 # Blockquote
-Allows you to use the `<blockquote>` HTML tag in the editor.
+The Blockquote extension enables you to use the `<blockquote>` HTML tag in the editor.
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | blockquote | none | Wrap content in a blockquote. |
 
-#### Keybindings
+## Keybindings
 * `Control` + `→`
 
-#### Example
+## Usage
 ```markup
 <template>
   <div>
diff --git a/docs/src/docPages/api/extensions/bold.md b/docs/src/docPages/api/extensions/bold.md
index c70f9ee4..cf541c24 100644
--- a/docs/src/docPages/api/extensions/bold.md
+++ b/docs/src/docPages/api/extensions/bold.md
@@ -1,23 +1,23 @@
 # Bold
-Renders text in **bold** text weight. If you pass `<strong>`, or `<b>` tags, or text with inline `style` attributes setting the `font-weight` CSS rule in the editor's initial content, they will be rendered accordingly.
+Renders text in **bold** text weight. If you pass `<strong>`, `<b>` tags, or text with inline `style` attributes setting the `font-weight` CSS rule in the editor’s initial content, they all will be rendered accordingly.
 
 ::: warning Restrictions
-The extension will generate the corresponding `<strong>` HTML tags when reading contents of the `Editor` instance. All text marked as bold, regardless of method will be normalized to `<strong>` HTML tags.
+The extension will generate the corresponding `<strong>` HTML tags when reading contents of the `Editor` instance. All text marked as bold, regardless of the method will be normalized to `<strong>` HTML tags.
 :::
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | bold | none | Mark text as bold. |
 
-#### Keybindings
+## Keybindings
 * Windows & Linux: `Control` + `B`
 * macOS: `Command` + `B`
 
-#### Example
+## Usage
 
 ```markup
 <template>
diff --git a/docs/src/docPages/api/extensions/bulletlist.md b/docs/src/docPages/api/extensions/bulletlist.md
index e7223f44..8c85b190 100644
--- a/docs/src/docPages/api/extensions/bulletlist.md
+++ b/docs/src/docPages/api/extensions/bulletlist.md
@@ -1,22 +1,22 @@
 # BulletList
-Allows you to use the `<ul>` HTML tag in the editor.
+This extension enables you to use the `<ul>` HTML tag in the editor.
 
 ::: warning Restrictions
-This extensions is intended to be used with the `ListItem` extension.
+It’s intended to be used with the `ListItem` extension.
 :::
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | bullet_list | none | Toggle a bullet list. |
 
-#### Keybindings
+## Keybindings
 * `Control` + `Shift` + `8`
 
-#### Example
+## Usage
 
 ```markup
 <template>
diff --git a/docs/src/docPages/api/extensions/code.md b/docs/src/docPages/api/extensions/code.md
index 20f555df..0ad425dd 100644
--- a/docs/src/docPages/api/extensions/code.md
+++ b/docs/src/docPages/api/extensions/code.md
@@ -1,18 +1,18 @@
 # Code
-Allows you to use the `<code>` HTML tag in the editor.
+The Code extensions enables you to use the `<code>` HTML tag in the editor.
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | code | none | Mark text as code. |
 
-#### Keybindings
+## Keybindings
 * `Alt` + `
 
-#### Example
+## Usage
 ```markup
 <template>
   <div>
diff --git a/docs/src/docPages/api/extensions/codeblock.md b/docs/src/docPages/api/extensions/codeblock.md
index 2f00e808..fad8b4a3 100644
--- a/docs/src/docPages/api/extensions/codeblock.md
+++ b/docs/src/docPages/api/extensions/codeblock.md
@@ -1,18 +1,2 @@
 # CodeBlock
-Allows you to use the `<pre>` HTML tag in the editor.
-
-## CodeBlockHighlight
-Allows you to use the `<pre>` HTML tag with auto-detected syntax highlighting in the editor.
-
-## Collaboration
-Allows you to collaborate with others on one document.
-
-## HardBreak
-Allows you to use the `<br>` HTML tag in the editor.
-
-#### Options
-*None*
-
-#### Keybindings
-* New CodeBlock: `Shift` + `Enter` + `
-* Leave CodeBlock: `Command` + `Enter`
+Enables you to use the `<pre>` HTML tag in the editor.
diff --git a/docs/src/docPages/api/extensions/codeblockheighlight.md b/docs/src/docPages/api/extensions/codeblockheighlight.md
new file mode 100644
index 00000000..53411a4b
--- /dev/null
+++ b/docs/src/docPages/api/extensions/codeblockheighlight.md
@@ -0,0 +1,2 @@
+# CodeBlockHighlight
+Enables you to use the `<pre>` HTML tag with auto-detected syntax highlighting in the editor.
\ No newline at end of file
diff --git a/docs/src/docPages/api/extensions/collaboration.md b/docs/src/docPages/api/extensions/collaboration.md
new file mode 100644
index 00000000..4e3c5805
--- /dev/null
+++ b/docs/src/docPages/api/extensions/collaboration.md
@@ -0,0 +1,2 @@
+# Collaboration
+Enables you to collaborate with others on one document.
\ No newline at end of file
diff --git a/docs/src/docPages/api/extensions/hardbreak.md b/docs/src/docPages/api/extensions/hardbreak.md
new file mode 100644
index 00000000..4d81abd9
--- /dev/null
+++ b/docs/src/docPages/api/extensions/hardbreak.md
@@ -0,0 +1,9 @@
+# HardBreak
+Enables you to use the `<br>` HTML tag in the editor.
+
+## Options
+*None*
+
+## Keybindings
+* New CodeBlock: `Shift` + `Enter` + `
+* Leave CodeBlock: `Command` + `Enter`
\ No newline at end of file
diff --git a/docs/src/docPages/api/extensions/heading.md b/docs/src/docPages/api/extensions/heading.md
index e643bb08..1722819c 100644
--- a/docs/src/docPages/api/extensions/heading.md
+++ b/docs/src/docPages/api/extensions/heading.md
@@ -1,17 +1,17 @@
 # Heading
-Allows you to use the headline HTML tags in the editor.
+Enables you to use the headline HTML tags in the editor.
 
-#### Options
+## Options
 | option | type | default | description |
 | ------ | ---- | ---- | ----- |
 | levels | Array | [1, 2, 3, 4, 5, 6] | Specifies which headlines are to be supported. |
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | heading | level | Creates a heading node. |
 
-#### Keybindings
+## Keybindings
 * `Control` + `Shift` + `1` → H1
 * `Control` + `Shift` + `2` → H2
 * `Control` + `Shift` + `3` → H3
@@ -19,7 +19,7 @@ Allows you to use the headline HTML tags in the editor.
 * `Control` + `Shift` + `5` → H5
 * `Control` + `Shift` + `6` → H6
 
-#### Example
+## Usage
 ```markup
 <template>
   <div>
diff --git a/docs/src/docPages/api/extensions/history.md b/docs/src/docPages/api/extensions/history.md
index 58e3f866..b7cdf189 100644
--- a/docs/src/docPages/api/extensions/history.md
+++ b/docs/src/docPages/api/extensions/history.md
@@ -1,19 +1,19 @@
 # History
 Enables history support.
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | undo | none | Undo the latest change. |
 | redo | none | Redo the latest change. |
 
-#### Keybindings
+## Keybindings
 * Windows & Linux: `Control` + `Z` → Undo
 * Windows & Linux: `Shift` + `Control` + `Z` → Redo
 * macOS: `Command` + `Z` → Undo
 * macOS: `Shift` + `Command` + `Z` → Redo
 
-#### Example
+## Usage
 ```markup
 <template>
   <div>
diff --git a/docs/src/docPages/api/extensions/horizontalrule.md b/docs/src/docPages/api/extensions/horizontalrule.md
index eb009086..d877655d 100644
--- a/docs/src/docPages/api/extensions/horizontalrule.md
+++ b/docs/src/docPages/api/extensions/horizontalrule.md
@@ -1,18 +1,18 @@
 # HorizontalRule
-Allows you to use the `<hr>` HTML tag in the editor.
+Enables you to use the `<hr>` HTML tag in the editor.
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | horizontal_rule | none | Create a horizontal rule. |
 
-#### Keybindings
+## Keybindings
 *None*
 
-#### Example
+## Usage
 ```markup
 <template>
   <div>
diff --git a/docs/src/docPages/api/extensions/italic.md b/docs/src/docPages/api/extensions/italic.md
index 5265ef00..88e4199d 100644
--- a/docs/src/docPages/api/extensions/italic.md
+++ b/docs/src/docPages/api/extensions/italic.md
@@ -1,19 +1,19 @@
 # Italic
-Allows you to use the `<em>` HTML tag in the editor.
+Enables you to use the `<em>` HTML tag in the editor.
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | italic | none | Mark text as italic. |
 
-#### Keybindings
+## Keybindings
 * Windows & Linux: `Control` + `I`
 * macOS: `Command` + `I`
 
-#### Example
+## Usage
 ```markup
 <template>
   <div>
diff --git a/docs/src/docPages/api/extensions/link.md b/docs/src/docPages/api/extensions/link.md
index 9f8e9bfc..900cf2dc 100644
--- a/docs/src/docPages/api/extensions/link.md
+++ b/docs/src/docPages/api/extensions/link.md
@@ -1,7 +1,7 @@
 # Link
-Allows you to use the `<a>` HTML tag in the editor.
+Enables you to use the `<a>` HTML tag in the editor.
 
-#### Options
+## Options
 | option | type | default | description |
 | ------ | ---- | ---- | ----- |
 | openOnClick | Boolean | true | Specifies if links will be opened on click. |
\ No newline at end of file
diff --git a/docs/src/docPages/api/extensions/listitem.md b/docs/src/docPages/api/extensions/listitem.md
index 2535087d..8d3dc689 100644
--- a/docs/src/docPages/api/extensions/listitem.md
+++ b/docs/src/docPages/api/extensions/listitem.md
@@ -1,5 +1,5 @@
 # ListItem
-Allows you to use the `<li>` HTML tag in the editor.
+Enables you to use the `<li>` HTML tag in the editor.
 
 ::: warning Restrictions
 This extensions is intended to be used with the `BulletList` or `OrderedList` extension.
diff --git a/docs/src/docPages/api/extensions/mention.md b/docs/src/docPages/api/extensions/mention.md
index 2a0c7935..2fe86278 100644
--- a/docs/src/docPages/api/extensions/mention.md
+++ b/docs/src/docPages/api/extensions/mention.md
@@ -1,2 +1,2 @@
 ## Mention
-Allows you to use mentions in the editor.
\ No newline at end of file
+Enables you to use mentions in the editor.
\ No newline at end of file
diff --git a/docs/src/docPages/api/extensions/orderedlist.md b/docs/src/docPages/api/extensions/orderedlist.md
index a8fb9131..f3c32e7d 100644
--- a/docs/src/docPages/api/extensions/orderedlist.md
+++ b/docs/src/docPages/api/extensions/orderedlist.md
@@ -1,22 +1,22 @@
 # OrderedList
-Allows you to use the `<ol>` HTML tag in the editor.
+Enables you to use the `<ol>` HTML tag in the editor.
 
 ::: warning Restrictions
 This extensions is intended to be used with the `ListItem` extension.
 :::
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | ordered_list | none | Toggle an ordered list. |
 
-#### Keybindings
+## Keybindings
 * `Control` + `Shift` + `9`
 
-#### Example
+## Usage
 ```markup
 <template>
   <div>
diff --git a/docs/src/docPages/api/extensions/placeholder.md b/docs/src/docPages/api/extensions/placeholder.md
index 53a05b96..a5b1dc87 100644
--- a/docs/src/docPages/api/extensions/placeholder.md
+++ b/docs/src/docPages/api/extensions/placeholder.md
@@ -1,22 +1,22 @@
 # Placeholder
-Allows you to show placeholders on empty paragraphs.
+Enables you to show placeholders on empty paragraphs.
 
 ## Table
 This enables support for tables in your editor.
 Tables can be nested and allow all blocks to be used inside.
 Each `<TableCell>` includes a single `<Paragraph>`.
 
-#### Options
+## Options
 | option | type | default | description |
 | ------ | ---- | ---- | ----- |
 | resizable | Boolean | false | Enables the resizing of columns |
 
-#### Keybindings
+## Keybindings
 * `Tab` → Next Cell
 * `Shift` + `Tab` + ` → Previous Cell
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | createTable | ```{ rowsCount, colsCount, withHeaderRow }``` | Returns a table node of a given size. `withHeaderRow` defines whether the first row of the table will be a header row. |
 | deleteTable | none | Deletes the complete table which is active |
@@ -34,7 +34,7 @@ Each `<TableCell>` includes a single `<Paragraph>`.
 | setCellAttr | none | Returns a command that sets the given attribute to the given value, and is only available when the currently selected cell doesn't already have that attribute set to that value. |
 | fixTables | none | Inspect all tables in the given state's document and return a transaction that fixes them, if necessary. |
 
-#### Example
+## Usage
 ::: warning
 You have to include all table extensions (`TableHeader`, `TableCell` & `TableRow`)
 :::
diff --git a/docs/src/docPages/api/extensions/strike.md b/docs/src/docPages/api/extensions/strike.md
index 535d7fbd..f6bdc40f 100644
--- a/docs/src/docPages/api/extensions/strike.md
+++ b/docs/src/docPages/api/extensions/strike.md
@@ -1,19 +1,19 @@
 # Strike
-Allows you to use the `<s>` HTML tag in the editor.
+Enables you to use the `<s>` HTML tag in the editor.
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | strike | none | Mark text as strikethrough. |
 
-#### Keybindings
+## Keybindings
 * Windows & Linux: `Control` + `D`
 * macOS: `Command` + `D`
 
-#### Example
+## Usage
 
 ```markup
 <template>
diff --git a/docs/src/docPages/api/extensions/tablecell.md b/docs/src/docPages/api/extensions/tablecell.md
index bb6fa262..09a28533 100644
--- a/docs/src/docPages/api/extensions/tablecell.md
+++ b/docs/src/docPages/api/extensions/tablecell.md
@@ -1,5 +1,5 @@
 # TableCell
-Allows you to use the `<td>` HTML tag in the editor.
+Enables you to use the `<td>` HTML tag in the editor.
 
 ::: warning Restrictions
 This extensions is intended to be used with the `Table` extension.
diff --git a/docs/src/docPages/api/extensions/tableheader.md b/docs/src/docPages/api/extensions/tableheader.md
index fed33494..25731c27 100644
--- a/docs/src/docPages/api/extensions/tableheader.md
+++ b/docs/src/docPages/api/extensions/tableheader.md
@@ -1,5 +1,5 @@
 # TableHeader
-Allows you to use the `<th>` HTML tag in the editor.
+Enables you to use the `<th>` HTML tag in the editor.
 
 ::: warning Restrictions
 This extensions is intended to be used with the `Table` extension.
diff --git a/docs/src/docPages/api/extensions/tablerow.md b/docs/src/docPages/api/extensions/tablerow.md
index d40381f2..748e0c8c 100644
--- a/docs/src/docPages/api/extensions/tablerow.md
+++ b/docs/src/docPages/api/extensions/tablerow.md
@@ -1,5 +1,5 @@
 # TableRow
-Allows you to use the `<tr>` HTML tag in the editor.
+Enables you to use the `<tr>` HTML tag in the editor.
 
 ::: warning Restrictions
 This extensions is intended to be used with the `Table` extension.
diff --git a/docs/src/docPages/api/extensions/todoitem.md b/docs/src/docPages/api/extensions/todoitem.md
index 42fdb33f..4896cf45 100644
--- a/docs/src/docPages/api/extensions/todoitem.md
+++ b/docs/src/docPages/api/extensions/todoitem.md
@@ -5,13 +5,13 @@ It renders a single toggleable item of a list.
 This extensions is intended to be used with the `TodoList` extension.
 :::
 
-#### Options
+## Options
 | option | type | default | description |
 | ------ | ---- | ---- | ----- |
 | nested | Boolean | false | Specifies if you can nest todo lists. |
 
-#### Commands
+## Commands
 *None*
 
-#### Keybindings
+## Keybindings
 *None*
\ No newline at end of file
diff --git a/docs/src/docPages/api/extensions/todolist.md b/docs/src/docPages/api/extensions/todolist.md
index dd7a57d1..a3669e70 100644
--- a/docs/src/docPages/api/extensions/todolist.md
+++ b/docs/src/docPages/api/extensions/todolist.md
@@ -5,18 +5,18 @@ Renders a toggleable list of items.
 This extensions is intended to be used with the `TodoItem` extension.
 :::
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | todo_list | none | Toggle todo list. |
 
-#### Keybindings
+## Keybindings
 *None*
 
-#### Example
+## Usage
 ```markup
 <template>
   <div>
diff --git a/docs/src/docPages/api/extensions/underline.md b/docs/src/docPages/api/extensions/underline.md
index ebfeb336..aedb2aeb 100644
--- a/docs/src/docPages/api/extensions/underline.md
+++ b/docs/src/docPages/api/extensions/underline.md
@@ -1,19 +1,19 @@
 # Underline
-Allows you to use the `<u>` HTML tag in the editor.
+Enables you to use the `<u>` HTML tag in the editor.
 
-#### Options
+## Options
 *None*
 
-#### Commands
-| command | options | description |
+## Commands
+| Command | Options | Description |
 | ------ | ---- | ---------------- |
 | underline | none | Mark text as underlined. |
 
-#### Keybindings
+## Keybindings
 * Windows & Linux: `Control` + `U`
 * macOS: `Command` + `U`
 
-#### Example
+## Usage
 
 ```markup
 <template>
diff --git a/docs/src/docPages/api/schema.md b/docs/src/docPages/api/schema.md
index 5086ca40..98fa3c0e 100644
--- a/docs/src/docPages/api/schema.md
+++ b/docs/src/docPages/api/schema.md
@@ -1,6 +1,6 @@
 # Schema
 
-Unlike many other editors, tiptap is based on a [schema](https://prosemirror.net/docs/guide/#schema) that defines how your content is structured. This allows you to define the kind of nodes that may occur in the document, its attributes and the way they can be nested.
+Unlike many other editors, tiptap is based on a [schema](https://prosemirror.net/docs/guide/#schema) that defines how your content is structured. This enables you to define the kind of nodes that may occur in the document, its attributes and the way they can be nested.
 
 This schema is *very* strict. You can’t use any HTML-element or attribute that is not defined in your schema.
 
diff --git a/docs/src/links.yaml b/docs/src/links.yaml
index 2a51562a..9bd67709 100644
--- a/docs/src/links.yaml
+++ b/docs/src/links.yaml
@@ -88,6 +88,12 @@
           link: /api/extensions/code
         - title: CodeBlock
           link: /api/extensions/codeblock
+        - title: CodeBlockHeighlight
+          link: /api/extensions/codeblockheighlight
+        - title: Collaboration
+          link: /api/extensions/collaboration
+        - title: Hardbreak
+          link: /api/extensions/hardbreak
         - title: Heading
           link: /api/extensions/heading
         - title: History