ianhitchman/tiptap
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'main' into feature/new-highlight-extension

Browse Source 
# Conflicts:
#	docs/src/docPages/api/extensions.md
#	docs/src/links.yaml
#	packages/core/src/extensions/toggleMark.ts
This commit is contained in:
Philipp Kühn
2020-11-05 21:27:20 +01:00
parent 228ef24424 44a2839d41
commit 9103172837
245 changed files with 4197 additions and 2609 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/src/docPages/api/commands.md
View File

@@ -1,6 +1,6 @@
# Commands
## Table of Contents
## toc
## Introduction
The editor provides a ton of commands to programmtically add or change content or alter the selection. If you want to build your own editor you definitely want to learn more about them.
@@ -14,7 +14,7 @@ editor.bold()
While that’s perfectly fine and does make the selected bold, you’d likely want to change multiple commands in one run. Let’s have a look at how that works.
## Chain commands
### Chain commands
Most commands can be executed combined to one call. First of all, that’s shorter than separate function call in most cases. Here is an example to make the selected text bold:
```js
@@ -27,35 +27,84 @@ When a user clicks on a button outside of the content, the editor isn’t in foc
All chained commands are kind of queued up. They are combined to one single transaction. That means, the content is only updated once, also the `update` event is only triggered once.
### Dry run for commands
Sometimes, you don’t want to actually run the commands, but only know if it would be possible to run commands, for example to show or hide buttons in a menu. That’s what we added `.can()` for. Everything coming after this method will be executed, without applying the changes to the document:
```js
editor.can().bold()
```
And you can use it together with `.chain()`, too. Here is an example which checks if it’s possible to apply all the commands:
```js
editor.can().chain().bold().italic().run()
```
Both calls would return `true` if it’s possible to apply the commands, and `false` in case it’s not.
### Try commands
If you want to run a list of commands, but want only the first successful command to be applied, you can do this with the `.try()` method. This method runs one command after the other and stops at the first which returns `true`.
For example, the backspace key tries to undo an input rule first. If that was successful, it stops there. If no input rule has been applied and thus can’t be reverted, it runs the next command and deletes the selection, if there is one. Here is the simplified example:
```js
editor.try(({ commands }) => [
() => commands.undoInputRule(),
() => commands.deleteSelection(),
// …
])
```
Inside of commands you can do the same thing like that:
```js
commands.try([
() => commands.undoInputRule(),
() => commands.deleteSelection(),
// …
])
```
## List of commands
Have a look at all of the core commands listed below. They should give you a good first impression of what’s possible.
### Content
| Command | Description |
| --------------- | ----------------------------------------------------------- |
| .clearContent() | Clear the whole document. |
| .insertgetHTML() | Insert a string of HTML at the currently selected position. |
| .insertText() | Insert a string of text at the currently selected position. |
| .setContent() | Replace the whole document with new content. |
| Command | Description |
| ---------------- | ----------------------------------------------------------- |
| .clearContent() | Clear the whole document. |
| .insertgetHTML() | Insert a string of HTML at the currently selected position. |
| .insertText() | Insert a string of text at the currently selected position. |
| .insertHTML() | |
| .setContent() | Replace the whole document with new content. |
### Nodes & Marks
| Command | Description |
| ------------------- | ------------------------------------------------------ |
| .removeMark() | Remove a mark in the current selection. |
| .removeMarks() | Remove all marks in the current selection. |
| .selectParentNode() | Select the parent node. |
| .toggleMark() | Toggle a mark on and off. |
| .toggleBlockType() | Toggle a node with another node. |
| .setBlockType() | Replace a given range with a node. |
| .updateMark() | Update a mark with new attributes. |
| Command | Description |
| ---------------------- | ------------------------------------------ |
| .clearNodes() | |
| .removeMark() | |
| .removeMark() | Remove a mark in the current selection. |
| .removeMarks() | |
| .removeMarks() | Remove all marks in the current selection. |
| .resetNodeAttributes() | |
| .selectParentNode() | Select the parent node. |
| .setBlockType() | Replace a given range with a node. |
| .setNodeAttributes() | |
| .splitBlock() | Forks a new node from an existing node. |
| .toggleBlockType() | Toggle a node with another node. |
| .toggleMark() | |
| .toggleMark() | Toggle a mark on and off. |
| .toggleWrap() | |
| .updateMark() | |
| .updateMark() | Update a mark with new attributes. |
### Lists
| Command | Description |
| ------------------- | ------------------------------------------------------ |
| .liftListItem() | Lift the list item into a wrapping list. |
| .sinkListItem() | Sink the list item down into an inner list. |
| .splitListItem() | Splits a textblock of a list item into two list items. |
| .toggleList() | Toggle between different list styles. |
| Command | Description |
| ---------------- | ------------------------------------------------------ |
| .liftListItem() | Lift the list item into a wrapping list. |
| .sinkListItem() | Sink the list item down into an inner list. |
| .splitListItem() | Splits a textblock of a list item into two list items. |
| .toggleList() | Toggle between different list styles. |
| .wrapInList() | |
### Selection
| Command | Description |
@@ -66,5 +115,7 @@ Have a look at all of the core commands listed below. They should give you a goo
| .scrollIntoView() | Scroll the selection into view. |
| .selectAll() | Select the whole document. |
### Extensions
All extension can add additional commands (and most do), check out the specific [documentation for the provided extensions](/api/extensions) to learn more about that. Of course, you can [add your custom extensions](/guide/custom-extensions) with custom commands aswell.
## Add your own commands
All extensions can add additional commands (and most do), check out the specific [documentation for the provided nodes](/api/nodes), [marks](/api/marks), and [extensions](/api/extensions) to learn more about those.
Of course, you can [add your custom extensions](/guide/build-custom-extensions) with custom commands aswell.

13
docs/src/docPages/api/editor.md
View File

@@ -1,6 +1,6 @@
# Editor
## Table of Contents
## toc
## 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.
@@ -10,25 +10,23 @@ This class is a central building block of tiptap. It does most of the heavy lift
| ------------------ | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `dropCursor` | `Object` | `{}` | Config for `prosemirror-dropcursor`. |
| `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). |
| `enableDropCursor` | `Boolean` | `true` | Enable/disable showing a cursor at the drop position when something is dragged over the editor. |
| `enableGapCursor` | `Boolean` | `true` | Enable/disable a cursor at places that don’t allow regular selection (such as positions that have a leaf block node, table, or the end of the document both before and after them). |
| `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. |
| `onUpdate` | `Function` | `undefined` | Returns an object with the current `state` of Prosemirror, a `getJSON()` and `getHTML()` function and the `transaction` on every change. |
## Methods
| Method | Parameters | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `getHTML()` | – | Returns the current content as HTML. |
| `getJSON()` | – | Returns the current content as JSON. |
| `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. |
| `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. |
@@ -40,3 +38,4 @@ This class is a central building block of tiptap. It does most of the heavy lift
| `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<br>`attrs` Attributes of the node or mark | Returns if the currently selected node or mark is active. |
| `isEmpty()` | - | Check if there is no content. |

4
docs/src/docPages/api/events.md
View File

@@ -1,6 +1,6 @@
# Events
## Table of Contents
## toc
## Introduction
The editor fires a few different events that you can hook into. There are two ways to register event listeners:
@@ -31,6 +31,7 @@ const editor = new Editor({
## Option 2: Later
Or you can register your event listeners on a running editor instance:
### Bind event listeners
```js
editor.on('init', () => {
// The editor is ready.
@@ -54,7 +55,6 @@ editor.on('transaction', ({ transaction }) => {
```
### Unbind event listeners
If you need to unbind those event listeners at some point, you should register your event listeners with `.on()` and unbind them with `.off()` then.
```js

88
docs/src/docPages/api/extensions.md
View File

@@ -1,54 +1,60 @@
# Extensions
## Table of Contents
## toc
## Introduction
Extensions are the way to add functionality to tiptap. By default tiptap comes bare, without any of them, but we have a long list of extensions that are ready to be used with tiptap.
## A minimalist set of extensions
You’ll need at least three extensions: `Document`, `Paragraph` and `Text`. See [an example of a tiptap version for minimalists](/examples/minimalist).
## Default extensions
You don’t have to use it, but we prepared a `@tiptap/vue-starter-kit` which includes the most common extensions. See [how you can use the `defaultExtensions()`](/examples/basic).
## List of supported extensions
## List of provided extensions
| Title | Default Extension | Source Code |
| ----------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
| [Blockquote](/api/extensions/blockquote) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-blockquote/) |
| [Bold](/api/extensions/bold) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/) |
| [BulletList](/api/extensions/bullet-list) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/) |
| [Code](/api/extensions/code) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code/) |
| [CodeBlock](/api/extensions/code-block) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code-block/) |
| [Collaboration](/api/extensions/collaboration) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-collaboration/) |
| [CollaborationCursor](/api/extensions/collaboration-cursor) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-collaboration-cursor/) |
| [Document](/api/extensions/document) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-document/) |
| [HardBreak](/api/extensions/hard-break) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-hard-break/) |
| [Heading](/api/extensions/heading) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-heading/) |
| [Highlight](/api/extensions/highlight) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-highlight/) |
| [History](/api/extensions/history) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-history/) |
| [HorizontalRule](/api/extensions/horizontal-rule) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-horizontal-rule/) |
| [Italic](/api/extensions/italic) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-italic/) |
| [Link](/api/extensions/link) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-link/) |
| [ListItem](/api/extensions/list-item) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-list-item/) |
| [OrderedList](/api/extensions/ordered-list) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-ordered-list/) |
| [Paragraph](/api/extensions/paragraph) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-paragraph/) |
| [Strike](/api/extensions/strike) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-strike/) |
| [Text](/api/extensions/text) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text/) |
| [Underline](/api/extensions/underline) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-underline/) |
| [Dropcursor](/api/extensions/dropcursor) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-dropcursor/) |
| [Focus](/api/extensions/focus) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-focus/) |
| [Gapcursor](/api/extensions/gapcursor) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-gapcursor/) |
| [History](/api/extensions/history) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-history/) |
| [TextAlign](/api/extensions/text-align) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text-align/) |
| [Typography](/api/extensions/typography) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-typography/) |
<!-- | [CodeBlockHighlight](/api/extensions/code-block-highlight) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packagescode-block-highlight/extension-/) -->
<!-- | [Mention](/api/extensions/mention) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-mention/) -->
<!-- | [Placeholder](/api/extensions/placeholder) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-placeholder/) -->
<!-- | [TableCell](/api/extensions/table-cell) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-table-cell/) -->
<!-- | [TableHeader](/api/extensions/table-header) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-table-header/) -->
<!-- | [TableRow](/api/extensions/table-row) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-table-row/) -->
<!-- | [TodoItem](/api/extensions/todo-item) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-todo-item/) -->
<!-- | [TodoList](/api/extensions/todo-list) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-todo-list/) -->
You don’t have to use it, but we prepared a `@tiptap/vue-starter-kit` which includes the most common extensions. Learn [how you can use the `defaultExtensions()`](/examples/basic).
## Community extensions
:::warning Work in Progress
This section is not ready yet. Meanwhile, [search through GitHub issues](https://github.com/ueberdosis/tiptap/issues) to find code snippets.
:::
## Create a new extension
You’re free to create your own extensions for tiptap. Here is the boilerplate code that’s need to create and register your own extension:
## Your custom extensions
Didn’t find what you’re looking for? No worries, [you can build your own extensions](/guide/custom-extensions).
```js
import { createExtension } from '@tiptap/core'
const CustomExtension = createExtension({
// Your code here
})
const editor = new Editor({
extensions: [
// Register your custom extension with the editor.
CustomExtension(),
// … and don’t forget all other extensions.
Document(),
Paragraph(),
Text(),
// …
],
```
Learn [more about custom extensions in our guide](/guide/build-custom-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 = createExtension({
addProseMirrorPlugins() {
return [
history(),
// …
]
},
})
```

11
docs/src/docPages/api/extensions/code-block-highlight.md
View File

@@ -1,11 +0,0 @@
# CodeBlockHighlight
Enables you to use the `<pre>` HTML tag with auto-detected syntax highlighting in the editor.
## Settings
*None*
## Commands
*None*
## Keyboard shortcuts
*None*

32
docs/src/docPages/api/extensions/collaboration-cursor.md
View File

@@ -1,2 +1,34 @@
# Collaboration Cursor
:::premium Premium Extension
Using this in production requires a **tiptap pro** license. [Read more](/sponsor)
:::
## Installation
```bash
# with npm
npm install @tiptap/extension-collaboration-cursor
# with Yarn
yarn add @tiptap/extension-collaboration-cursor
```
## Settings
| Option | Type | Default | Description |
| -------- | ---- | ------- | ----------- |
| provider | | | |
| type | | | |
## Commands
| Command | Parameters | Description |
| ------- | ------------- | ------------------------------------------------------------------------ |
| user | name<br>color | The name of the current user.<br>The color of the current user’s cursor. |
## Source code
[packages/extension-collaboration-cursor/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-collaboration-cursor/)
## Usage
:::warning Public
The content of this editor is shared with other users.
:::
<demo name="Extensions/CollaborationCursor" highlight="" />

10
docs/src/docPages/api/extensions/collaboration.md
View File

@@ -1,12 +1,16 @@
# Collaboration
Enables you to collaborate with others on one document.
The Collaboration extension enables you to collaborate with others on one document. The implementation is based on [Y.js by Kevin Jahns](https://github.com/yjs/yjs), which is the coolest thing to [integrate collaborative editing](/guide/collaborative-editing) in your project.
:::premium Premium Extension
Using this in production requires a **tiptap pro** license. [Read more](/sponsor)
:::
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-collaboration yjs y-webrtc
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-collaboration yjs y-webrtc
```

25
docs/src/docPages/api/extensions/dropcursor.md Normal file
View File

@@ -0,0 +1,25 @@
# Dropcursor
## Installation
```bash
# with npm
npm install @tiptap/extension-dropcursor
# with Yarn
yarn add @tiptap/extension-dropcursor
```
## Settings
*None*
## Commands
*None*
## Keyboard shortcuts
*None*
## Source code
[packages/extension-dropcursor/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-dropcursor/)
## Usage
<demo name="Extensions/Dropcursor" highlight="" />

22
docs/src/docPages/api/extensions/focus.md Normal file
View File

@@ -0,0 +1,22 @@
# Focus
## Installation
```bash
# with npm
npm install @tiptap/extension-focus
# with Yarn
yarn add @tiptap/extension-focus
```
## Settings
| Option | Type | Default | Description |
| --------- | ------- | --------- | ------------------------------------------------------ |
| className | string | has-focus | The class that is applied to the focused element. |
| nested | boolean | true | When enabled nested elements get the focus class, too. |
## Source code
[packages/extension-focus/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-focus/)
## Usage
<demo name="Extensions/Focus" highlight="31-34,12" />

19
docs/src/docPages/api/extensions/gapcursor.md Normal file
View File

@@ -0,0 +1,19 @@
# Gapcursor
This extension loads the [ProseMirror Gapcursor plugin](https://github.com/ProseMirror/prosemirror-gapcursor) by Marijn Haverbeke, which adds a gap for the cursor in places that don’t allow regular selection. For example, after a table at the end of a document.
Note that tiptap is renderless, but the dropcursor needs CSS for its appearance. The default CSS is added to the usage example below.
## Installation
```bash
# with npm
npm install @tiptap/extension-gapcursor
# with Yarn
yarn add @tiptap/extension-gapcursor
```
## Source code
[packages/extension-gapcursor/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-gapcursor/)
## Usage
<demo name="Extensions/Gapcursor" highlight="12,33" />

6
docs/src/docPages/api/extensions/history.md
View File

@@ -3,10 +3,10 @@ This extension provides history support. All changes to the document will be tra
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-history
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-history
```
@@ -17,7 +17,7 @@ yarn add @tiptap/extension-history
| newGroupDelay | number | 500 | The delay between changes after which a new group should be started (in milliseconds). When changes aren’t adjacent, a new group is always started. |
## Commands
| Command | Options | Description |
| Command | Parameters | Description |
| ------- | ------- | --------------------- |
| undo | — | Undo the last change. |
| redo | — | Redo the last change. |

16
docs/src/docPages/api/extensions/image.md
View File

@@ -1,16 +0,0 @@
# Image
## Installation
```bash
# With npm
npm install @tiptap/extension-image
# Or: With Yarn
yarn add @tiptap/extension-image
```
## Source code
[packages/extension-image/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-image/)
## Usage
<demo name="Extensions/Image" highlight="12,30" />

2
docs/src/docPages/api/extensions/mention.md
View File

@@ -1,2 +0,0 @@
# Mention
Enables you to use mentions in the editor.

2
docs/src/docPages/api/extensions/placeholder.md
View File

@@ -1,2 +0,0 @@
# Placeholder
Enables you to show placeholders on empty paragraphs.

6
docs/src/docPages/api/extensions/table-cell.md
View File

@@ -1,6 +0,0 @@
# TableCell
Enables you to use the `<td>` HTML tag in the editor.
::: warning Restrictions
This extensions is intended to be used with the `Table` extension.
:::

6
docs/src/docPages/api/extensions/table-header.md
View File

@@ -1,6 +0,0 @@
# TableHeader
Enables you to use the `<th>` HTML tag in the editor.
::: warning Restrictions
This extensions is intended to be used with the `Table` extension.
:::

6
docs/src/docPages/api/extensions/table-row.md
View File

@@ -1,6 +0,0 @@
# TableRow
Enables you to use the `<tr>` HTML tag in the editor.
::: warning Restrictions
This extensions is intended to be used with the `Table` extension.
:::

15
docs/src/docPages/api/extensions/text-align.md
View File

@@ -1,14 +1,23 @@
# Text Align
# TextAlign
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-text-align
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-text-align
```
## Settings
*None*
## Commands
*None*
## Keyboard shortcuts
*None*
## Source code
[packages/extension-text-align/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text-align/)

17
docs/src/docPages/api/extensions/todo-item.md
View File

@@ -1,17 +0,0 @@
# TodoItem
It renders a single toggleable item of a list.
::: warning Restrictions
This extensions is intended to be used with the `TodoList` extension.
:::
## Settings
| Option | Type | Default | Description |
| ------ | ------- | ------- | ------------------------------------- |
| nested | Boolean | false | Specifies if you can nest todo lists. |
## Commands
*None*
## Keyboard shortcuts
*None*

69
docs/src/docPages/api/extensions/todo-list.md
View File

@@ -1,69 +0,0 @@
# TodoList
Renders a toggleable list of items.
::: warning Restrictions
This extensions is intended to be used with the `TodoItem` extension.
:::
## Settings
*None*
## Commands
| Command | Options | Description |
| --------- | ------- | ----------------- |
| todo_list | — | Toggle todo list. |
## Keyboard shortcuts
*None*
## Usage
```markup
<template>
<div>
<editor-menu-bar :editor="editor" v-slot="{ commands, isActive }">
<button type="button" :class="{ 'is-active': isActive.todo_list() }" @click="commands.todo_list">
Todo List
</button>
</editor-menu-bar>
<editor-content :editor="editor" />
</div>
</template>
<script>
import { Editor, EditorContent, EditorMenuBar } from 'tiptap'
import { TodoItem, TodoList } from 'tiptap-extensions'
export default {
components: {
EditorMenuBar,
EditorContent,
},
data() {
return {
editor: new Editor({
extensions: [
TodoItem({
nested: true,
}),
TodoList(),
],
content: `
<ul data-type="todo_list">
<li data-type="todo_item" data-done="true">
Checked item
</li>
<li data-type="todo_item" data-done="false">
Unchecked item
</li>
</ul>
`,
}),
}
},
beforeDestroy() {
this.editor.destroy()
}
}
</script>
```

17
docs/src/docPages/api/extensions/typography.md Normal file
View File

@@ -0,0 +1,17 @@
# Typography
## Installation
```bash
# with npm
npm install @tiptap/typography
# with Yarn
yarn add @tiptap/typography
```
## Source code
[packages/typography/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/typography/)
## Usage
<demo name="Extensions/Typography" highlight="" />

168
docs/src/docPages/api/keyboard-shortcuts.md
View File

@@ -1,8 +1,85 @@
# Keyboard Shortcuts
## Table of Contents
## toc
## Introduction
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!
Funfact: A while ago, we built a [keyboard shortcut learning app](https://mouseless.app), to which we manually added exercises for thousands of keyboard shortcuts for a bunch of tools.
## 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
❌ = untested
| 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` |
| 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` |
| ❌ 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` |
### 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` |
| ❌ Strikethrough | `Alt`&nbsp;`Shift`&nbsp;`5` | `Cmd`&nbsp;`Shift`&nbsp;`X` |
| ❌ 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;`\`<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;`[` |
| 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` |
| Apply heading style 3 | `Control`&nbsp;`Alt`&nbsp;`3` | `Cmd`&nbsp;`Alt`&nbsp;`3` |
| Apply heading style 4 | `Control`&nbsp;`Alt`&nbsp;`4` | `Cmd`&nbsp;`Alt`&nbsp;`4` |
| Apply heading style 5 | `Control`&nbsp;`Alt`&nbsp;`5` | `Cmd`&nbsp;`Alt`&nbsp;`5` |
| Apply heading style 6 | `Control`&nbsp;`Alt`&nbsp;`6` | `Cmd`&nbsp;`Alt`&nbsp;`6` |
| Left align | `Control`&nbsp;`Shift`&nbsp;`L` | `Cmd`&nbsp;`Shift`&nbsp;`L` |
| Center align | `Control`&nbsp;`Shift`&nbsp;`E` | `Cmd`&nbsp;`Shift`&nbsp;`E` |
| Right align | `Control`&nbsp;`Shift`&nbsp;`R` | `Cmd`&nbsp;`Shift`&nbsp;`R` |
| Justify | `Control`&nbsp;`Shift`&nbsp;`J` | `Cmd`&nbsp;`Shift`&nbsp;`J` |
| ❌ Numbered list | `Control`&nbsp;`Shift`&nbsp;`7` | `Cmd`&nbsp;`Shift`&nbsp;`7` |
| ❌ Bulleted list | `Control`&nbsp;`Shift`&nbsp;`8` | `Cmd`&nbsp;`Shift`&nbsp;`8` |
| ❌ Move paragraph up | `Control`&nbsp;`Shift`&nbsp;`↑` | `Control`&nbsp;`Shift`&nbsp;`↑` |
| ❌ 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;`↓` |
| ❌ 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>.
@@ -11,94 +88,27 @@ Modifiers can be given in any order. `Shift`, `Alt`, `Control` and `Cmd` are rec
You can use `Mod` as a shorthand for `Cmd` on Mac and `Control` on other platforms.
## Overwrite keyboard shortcuts
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()
.keys(({ editor }) => ({
// ↓ your new keyboard shortcut
'Mod-l': () => editor.bulletList(),
}))
.create() // Don’t forget that!
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(),
// …
CustomBulletList(),
// …
]
})
```
## Predefined keyboard shortcuts
### 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` |
| Paste without formatting | `Control`&nbsp;`Shift`&nbsp;`V` | `Cmd`&nbsp;`Shift`&nbsp;`V` |
| 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` |
| 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` |
### 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` |
| Strikethrough | `Alt`&nbsp;`Shift`&nbsp;`5` | `Cmd`&nbsp;`Shift`&nbsp;`X` |
| 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;`\` |
| 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;`[` |
| 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` |
| Apply heading style 3 | `Control`&nbsp;`Alt`&nbsp;`3` | `Cmd`&nbsp;`Alt`&nbsp;`3` |
| Apply heading style 4 | `Control`&nbsp;`Alt`&nbsp;`4` | `Cmd`&nbsp;`Alt`&nbsp;`4` |
| Apply heading style 5 | `Control`&nbsp;`Alt`&nbsp;`5` | `Cmd`&nbsp;`Alt`&nbsp;`5` |
| Apply heading style 6 | `Control`&nbsp;`Alt`&nbsp;`6` | `Cmd`&nbsp;`Alt`&nbsp;`6` |
| Left align | `Control`&nbsp;`Shift`&nbsp;`L` | `Cmd`&nbsp;`Shift`&nbsp;`L` |
| Center align | `Control`&nbsp;`Shift`&nbsp;`E` | `Cmd`&nbsp;`Shift`&nbsp;`E` |
| Right align | `Control`&nbsp;`Shift`&nbsp;`R` | `Cmd`&nbsp;`Shift`&nbsp;`R` |
| Justify | `Control`&nbsp;`Shift`&nbsp;`J` | `Cmd`&nbsp;`Shift`&nbsp;`J` |
| Numbered list | `Control`&nbsp;`Shift`&nbsp;`7` | `Cmd`&nbsp;`Shift`&nbsp;`7` |
| Bulleted list | `Control`&nbsp;`Shift`&nbsp;`8` | `Cmd`&nbsp;`Shift`&nbsp;`8` |
| Move paragraph up | `Control`&nbsp;`Shift`&nbsp;`↑` | `Control`&nbsp;`Shift`&nbsp;`↑` |
| 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;`↓` |
| 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;`↓` |

15
docs/src/docPages/api/marks.md Normal file
View File

@@ -0,0 +1,15 @@
# Marks
## toc
## Introduction
## List of supported marks
| Title | Default Extension | Source Code |
| --------------------------------- | ----------------- | ------------------------------------------------------------------------------------------- |
| [Bold](/api/marks/bold) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/) |
| [Code](/api/marks/code) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code/) |
| [Italic](/api/marks/italic) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-italic/) |
| [Link](/api/marks/link) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-link/) |
| [Strike](/api/marks/strike) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-strike/) |
| [Underline](/api/marks/underline) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-underline/) |

8
docs/src/docPages/api/extensions/bold.md → docs/src/docPages/api/marks/bold.md
View File

@@ -9,10 +9,10 @@ The extension will generate the corresponding `<strong>` HTML tags when reading
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-bold
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-bold
```
@@ -22,7 +22,7 @@ yarn add @tiptap/extension-bold
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| Command | Parameters | Description |
| ------- | ------- | --------------- |
| bold | — | Mark text bold. |
@@ -34,4 +34,4 @@ yarn add @tiptap/extension-bold
[packages/extension-bold/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/)
## Usage
<demo name="Extensions/Bold" highlight="3-5,17,36" />
<demo name="Marks/Bold" highlight="3-5,17,36" />

8
docs/src/docPages/api/extensions/code.md → docs/src/docPages/api/marks/code.md
View File

@@ -5,10 +5,10 @@ Type something with <code>\`back-ticks around\`</code> and it will magically tra
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-code
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-code
```
@@ -18,7 +18,7 @@ yarn add @tiptap/extension-code
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| Command | Parameters | Description |
| ------- | ------- | ------------------------- |
| code | — | Mark text as inline code. |
@@ -29,4 +29,4 @@ yarn add @tiptap/extension-code
[packages/extension-code/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code/)
## Usage
<demo name="Extensions/Code" highlight="3-5,17,36" />
<demo name="Marks/Code" highlight="3-5,17,36" />

0
docs/src/docPages/api/extensions/highlight.md → docs/src/docPages/api/marks/highlight.md
View File

8
docs/src/docPages/api/extensions/italic.md → docs/src/docPages/api/marks/italic.md
View File

@@ -9,10 +9,10 @@ The extension will generate the corresponding `<em>` HTML tags when reading cont
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-italic
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-italic
```
@@ -22,7 +22,7 @@ yarn add @tiptap/extension-italic
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| Command | Parameters | Description |
| ------- | ------- | ----------------- |
| italic | — | Mark text italic. |
@@ -34,4 +34,4 @@ yarn add @tiptap/extension-italic
[packages/extension-italic/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-italic/)
## Usage
<demo name="Extensions/Italic" highlight="3-5,17,36" />
<demo name="Marks/Italic" highlight="3-5,17,36" />

10
docs/src/docPages/api/extensions/link.md → docs/src/docPages/api/marks/link.md
View File

@@ -7,10 +7,10 @@ Pasted URLs will be linked automatically.
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-link
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-link
```
@@ -23,17 +23,17 @@ yarn add @tiptap/extension-link
| target | string | _blank | Set the default `target` of links. |
## Commands
| Command | Options | Description |
| Command | Parameters | Description |
| ------- | -------------- | ----------------------------------------------------------- |
| link | href<br>target | Link the selected text. Removes a link, if `href` is empty. |
## Keyboard shortcuts
:::warning Doesn’t have a keyboard shortcut
This extension doesn’t bind a specific keyboard shortcut. You would probably open your UI on `Mod-k` though.
This extension doesn’t bind a specific keyboard shortcut. You would probably open your custom UI on `Mod-k` though.
:::
## Source code
[packages/extension-link/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-link/)
## Usage
<demo name="Extensions/Link" highlight="3-8,19,38,55" />
<demo name="Marks/Link" highlight="3-8,19,38,55" />

8
docs/src/docPages/api/extensions/strike.md → docs/src/docPages/api/marks/strike.md
View File

@@ -9,10 +9,10 @@ The extension will generate the corresponding `<s>` HTML tags when reading conte
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-strike
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-strike
```
@@ -22,7 +22,7 @@ yarn add @tiptap/extension-strike
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| Command | Parameters | Description |
| ------- | ------- | --------------------------- |
| strike | — | Mark text as strikethrough. |
@@ -34,4 +34,4 @@ yarn add @tiptap/extension-strike
[packages/extension-strike/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-strike/)
## Usage
<demo name="Extensions/Strike" highlight="3-5,17,36" />
<demo name="Marks/Strike" highlight="3-5,17,36" />

12
docs/src/docPages/api/extensions/underline.md → docs/src/docPages/api/marks/underline.md
View File

@@ -9,10 +9,10 @@ The extension will generate the corresponding `<u>` HTML tags when reading conte
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-underline
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-underline
```
@@ -22,9 +22,9 @@ yarn add @tiptap/extension-underline
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| --------- | ------- | ------------------------ |
| underline | — | Mark text as underlined. |
| Command | Parameters | Description |
| --------- | ---------- | ------------------------ |
| underline | — | Mark text as underlined. |
## Keyboard shortcuts
* Windows/Linux: `Control`&nbsp;`U`
@@ -34,4 +34,4 @@ yarn add @tiptap/extension-underline
[packages/extension-underline/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-underline/)
## Usage
<demo name="Extensions/Underline" highlight="3-5,17,36" />
<demo name="Marks/Underline" highlight="3-5,17,36" />

23
docs/src/docPages/api/nodes.md Normal file
View File

@@ -0,0 +1,23 @@
# Nodes
## toc
## Introduction
## List of supported nodes
| Title | Default Extension | Source Code |
| -------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| [Blockquote](/api/nodes/blockquote) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-blockquote/) |
| [BulletList](/api/nodes/bullet-list) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/) |
| [CodeBlock](/api/nodes/code-block) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code-block/) |
| [Document](/api/nodes/document) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-document/) |
| [HardBreak](/api/nodes/hard-break) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-hard-break/) |
| [Heading](/api/nodes/heading) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-heading/) |
| [HorizontalRule](/api/nodes/horizontal-rule) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-horizontal-rule/) |
| [Image](/api/nodes/image) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-image/) |
| [ListItem](/api/nodes/list-item) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-list-item/) |
| [OrderedList](/api/nodes/ordered-list) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-ordered-list/) |
| [Paragraph](/api/nodes/paragraph) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-paragraph/) |
| [TaskItem](/api/nodes/task-item) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-task-item/) |
| [TaskList](/api/nodes/task-list) | – | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-task-list/) |
| [Text](/api/nodes/text) | Yes | [GitHub](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text/) |

12
docs/src/docPages/api/extensions/blockquote.md → docs/src/docPages/api/nodes/blockquote.md
View File

@@ -6,10 +6,10 @@ Type <code>>&nbsp;</code> at the beginning of a new line and it will magically t
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-blockquote
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-blockquote
```
@@ -19,9 +19,9 @@ yarn add @tiptap/extension-blockquote
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| ---------- | ------- | ----------------------------- |
| blockquote | — | Wrap content in a blockquote. |
| Command | Parameters | Description |
| ---------- | ---------- | ----------------------------- |
| blockquote | — | Wrap content in a blockquote. |
## Keyboard shortcuts
* Windows/Linux: `Control`&nbsp;`Shift`&nbsp;`9`
@@ -31,4 +31,4 @@ yarn add @tiptap/extension-blockquote
[packages/extension-blockquote/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-blockquote/)
## Usage
<demo name="Extensions/Blockquote" highlight="3-5,17,36" />
<demo name="Nodes/Blockquote" highlight="3-5,17,36" />

16
docs/src/docPages/api/extensions/bullet-list.md → docs/src/docPages/api/nodes/bullet-list.md
View File

@@ -1,18 +1,18 @@
# BulletList
This extension enables you to use bullet lists in the editor. They are rendered as `<ul>` HTML tags,
This extension enables you to use bullet lists in the editor. They are rendered as `<ul>` HTML tags.
Type <code>*&nbsp;</code>, <code>-&nbsp;</code> or <code>+&nbsp;</code> at the beginning of a new line and it will magically transform to a bullet list.
## Installation
::: warning Use with ListItem
The `BulletList` extension is intended to be used with the [`ListItem`](/api/extensions/list-item) extension. Make sure to import that one too, otherwise you’ll get a SyntaxError.
This extension requires the [`ListItem`](/api/nodes/list-item) extension.
:::
```bash
# With npm
# with npm
npm install @tiptap/extension-bullet-list @tiptap/extension-list-item
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-bullet-list @tiptap/extension-list-item
```
@@ -22,9 +22,9 @@ yarn add @tiptap/extension-bullet-list @tiptap/extension-list-item
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| ----------- | ------- | --------------------- |
| bullet_list | — | Toggle a bullet list. |
| Command | Parameters | Description |
| ----------- | ---------- | --------------------- |
| bulletList | — | Toggle a bullet list. |
## Keyboard shortcuts
* `Control`&nbsp;`Shift`&nbsp;`8`
@@ -33,4 +33,4 @@ yarn add @tiptap/extension-bullet-list @tiptap/extension-list-item
[packages/extension-bullet-list/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/)
## Usage
<demo name="Extensions/BulletList" highlight="3-5,17-18,37-38" />
<demo name="Nodes/BulletList" highlight="3-5,17-18,37-38" />

12
docs/src/docPages/api/extensions/code-block.md → docs/src/docPages/api/nodes/code-block.md
View File

@@ -9,10 +9,10 @@ The CodeBlock extension doesn’t come with styling and has no syntax highlighti
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-code-block
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-code-block
```
@@ -23,9 +23,9 @@ yarn add @tiptap/extension-code-block
| languageClassPrefix | string | language- | Adds a prefix to language classes that are applied to code tags. |
## Commands
| Command | Options | Description |
| --------- | ------- | ----------------------------- |
| codeBlock | — | Wrap content in a code block. |
| Command | Parameters | Description |
| --------- | ---------- | ----------------------------- |
| codeBlock | — | Wrap content in a code block. |
## Keyboard shortcuts
* Windows/Linux: `Control`&nbsp;`Shift`&nbsp;`C`
@@ -35,4 +35,4 @@ yarn add @tiptap/extension-code-block
[packages/extension-code-block/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code-block/)
## Usage
<demo name="Extensions/CodeBlock" highlight="3-5,17,36" />
<demo name="Nodes/CodeBlock" highlight="3-5,17,36" />

8
docs/src/docPages/api/extensions/document.md → docs/src/docPages/api/nodes/document.md
View File

@@ -4,15 +4,15 @@
The node is very tiny though. It defines a name of the node (`document`), is configured to be a top node (`topNode: true`) and that it can contain multiple other nodes (`block`). That’s all. But have a look yourself:
:::warning Breaking Change from 1.x → 2.x
Tiptap 1 tried to hide that node from you, but it has always been there. A tiny, but important change though: **We renamed the default 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.
tiptap 1 tried to hide that node from you, but it has always been there. A tiny, but important change though: **We renamed the default 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.
:::
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-document
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-document
```
@@ -20,4 +20,4 @@ yarn add @tiptap/extension-document
[packages/extension-document/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-document/)
## Usage
<demo name="Extensions/Document" highlight="10,28" />
<demo name="Nodes/Document" highlight="10,28" />

15
docs/src/docPages/api/extensions/hard-break.md → docs/src/docPages/api/nodes/hard-break.md
View File

@@ -3,20 +3,17 @@ The HardBreak extensions adds support for the `<br>` HTML tag, which forces a li
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-hard-break
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-hard-break
```
## Settings
*None*
## Commands
| Command | Options | Description |
| --------- | ------- | ----------------- |
| hardBreak | — | Add a line break. |
| Command | Parameters | Description |
| --------- | ---------- | ----------------- |
| hardBreak | — | Add a line break. |
## Keyboard shortcuts
* `Shift`&nbsp;`Enter`
@@ -27,4 +24,4 @@ yarn add @tiptap/extension-hard-break
[packages/extension-hard-break/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-hard-break/)
## Usage
<demo name="Extensions/HardBreak" highlight="3-5,17,36" />
<demo name="Nodes/HardBreak" highlight="3-5,17,36" />

12
docs/src/docPages/api/extensions/heading.md → docs/src/docPages/api/nodes/heading.md
View File

@@ -5,10 +5,10 @@ Type <code>#&nbsp;</code> at the beginning of a new line and it will magically t
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-heading
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-heading
```
@@ -19,9 +19,9 @@ yarn add @tiptap/extension-heading
| levels | Array | [1, 2, 3, 4, 5, 6] | Specifies which heading levels are supported. |
## Commands
| Command | Options | Description |
| ------- | ------- | ----------------------- |
| heading | level | Creates a heading node. |
| Command | Parameters | Description |
| ------- | ---------- | ------------------------------------------------ |
| heading | level | Creates a heading node with the specified level. |
## Keyboard shortcuts
* Windows/Linux: `Control`&nbsp;`Alt`&nbsp;`1-6`
@@ -31,4 +31,4 @@ yarn add @tiptap/extension-heading
[packages/extension-heading/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-heading/)
## Usage
<demo name="Extensions/Heading" highlight="3-11,23,42-44" />
<demo name="Nodes/Heading" highlight="3-11,23,42-44" />

12
docs/src/docPages/api/extensions/horizontal-rule.md → docs/src/docPages/api/nodes/horizontal-rule.md
View File

@@ -5,10 +5,10 @@ Type three dashes (<code>---</code>) or three underscores and a space (<code>___
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-horizontal-rule
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-horizontal-rule
```
@@ -18,9 +18,9 @@ yarn add @tiptap/extension-horizontal-rule
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| --------------- | ------- | ------------------------- |
| horizontalRule | — | Create a horizontal rule. |
| Command | Parameters | Description |
| -------------- | ---------- | ------------------------- |
| horizontalRule | — | Create a horizontal rule. |
## Keyboard shortcuts
*None*
@@ -29,4 +29,4 @@ yarn add @tiptap/extension-horizontal-rule
[packages/extension-horizontal-rule/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-horizontal-rule/)
## Usage
<demo name="Extensions/HorizontalRule" highlight="3-5,17,36" />
<demo name="Nodes/HorizontalRule" highlight="3-5,17,36" />

26
docs/src/docPages/api/nodes/image.md Normal file
View File

@@ -0,0 +1,26 @@
# Image
Use this extension to render `<img>` HTML tags. By default, those images are blocks. If you want to render images in line with text set the `inline` option to `true`.
:::warning Restrictions
This extension does only the rendering of images. It doesn’t upload images to your server, that’s a whole different story.
:::
## Installation
```bash
# with npm
npm install @tiptap/extension-image
# with Yarn
yarn add @tiptap/extension-image
```
## Settings
| Option | Type | Default | Description |
| ------ | ------- | ------- | ------------------------------ |
| inline | boolean | false | Renders the image node inline. |
## Source code
[packages/extension-image/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-image/)
## Usage
<demo name="Nodes/Image" />

13
docs/src/docPages/api/extensions/list-item.md → docs/src/docPages/api/nodes/list-item.md
View File

@@ -2,15 +2,15 @@
The ListItem extension adds support for the `<li>` HTML tag. It’s used for bullet lists and ordered lists and can’t really be used without them.
## Installation
::: warning Restrictions
This extensions is intended to be used with the [`BulletList`](/api/extensions/bullet-list) or [`OrderedList`](/api/extensions/ordered-list) extension. It doesn’t work without at least using one of them.
::: warning Use with BulletList and/or OrderedList
This extension requires the [`BulletList`](/api/nodes/bullet-list) or [`OrderedList`](/api/nodes/ordered-list) extension.
:::
```bash
# With npm
# with npm
npm install @tiptap/extension-list-item
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-list-item
```
@@ -19,9 +19,6 @@ yarn add @tiptap/extension-list-item
| ------ | ------ | ------- | -------------------------------------------- |
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
*None*
## Keyboard shortcuts
* New list item: `Enter`
* Sink a list item: `Tab`
@@ -31,4 +28,4 @@ yarn add @tiptap/extension-list-item
[packages/extension-list-item/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-list-item/)
## Usage
<demo name="Extensions/ListItem" highlight="3-8,20-22,41-43" />
<demo name="Nodes/ListItem" highlight="3-8,20-22,41-43" />

16
docs/src/docPages/api/extensions/ordered-list.md → docs/src/docPages/api/nodes/ordered-list.md
View File

@@ -1,18 +1,18 @@
# OrderedList
This extension enables you to use ordered lists in the editor. They are rendered as `<ol>` HTML tags,
This extension enables you to use ordered lists in the editor. They are rendered as `<ol>` HTML tags.
Type <code>1.&nbsp;</code> (or any other number followed by a dot) at the beginning of a new line and it will magically transform to a ordered list.
## Installation
::: warning Use with ListItem
The `OrderedList` extension is intended to be used with the [`ListItem`](/api/extensions/list-item) extension. Make sure to import that one too, otherwise you’ll get a SyntaxError.
This extension requires the [`ListItem`](/api/nodes/list-item) extension.
:::
```bash
# With npm
# with npm
npm install @tiptap/extension-ordered-list @tiptap/extension-list-item
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-ordered-list @tiptap/extension-list-item
```
@@ -22,9 +22,9 @@ yarn add @tiptap/extension-ordered-list @tiptap/extension-list-item
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| ------------ | ------- | ---------------------- |
| ordered_list | — | Toggle a ordered list. |
| Command | Parameters | Description |
| ----------- | ---------- | ----------------------- |
| orderedList | — | Toggle an ordered list. |
## Keyboard shortcuts
* `Control`&nbsp;`Shift`&nbsp;`9`
@@ -33,4 +33,4 @@ yarn add @tiptap/extension-ordered-list @tiptap/extension-list-item
[packages/extension-ordered-list/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-ordered-list/)
## Usage
<demo name="Extensions/OrderedList" highlight="3-5,17-18,37-38" />
<demo name="Nodes/OrderedList" highlight="3-5,17-18,37-38" />

14
docs/src/docPages/api/extensions/paragraph.md → docs/src/docPages/api/nodes/paragraph.md
View File

@@ -2,15 +2,15 @@
Yes, the schema is very strict. Without this extension you won’t even be able to use paragraphs in the editor.
:::warning Breaking Change from 1.x → 2.x
Tiptap 1 tried to hide that node from you, but it has always been there. You have to explicitly import it from now on (or use `defaultExtensions()`).
tiptap 1 tried to hide that node from you, but it has always been there. You have to explicitly import it from now on (or use `defaultExtensions()`).
:::
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-paragraph
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-paragraph
```
@@ -20,9 +20,9 @@ yarn add @tiptap/extension-paragraph
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
| --------- | ------- | -------------------------------------------- |
| paragraph | — | Transforms all selected nodes to paragraphs. |
| Command | Parameters | Description |
| --------- | ---------- | -------------------------------------------- |
| paragraph | — | Transforms all selected nodes to paragraphs. |
## Keyboard shortcuts
* Windows & Linux: `Control`&nbsp;`Alt`&nbsp;`0`
@@ -32,4 +32,4 @@ yarn add @tiptap/extension-paragraph
[packages/extension-paragraph/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-paragraph/)
## Usage
<demo name="Extensions/Paragraph" highlight="11,29" />
<demo name="Nodes/Paragraph" highlight="11,29" />

28
docs/src/docPages/api/nodes/task-item.md Normal file
View File

@@ -0,0 +1,28 @@
# TaskItem
## Installation
::: warning Use with TaskList
This extension requires the [`TaskList`](/api/nodes/task-list) extension.
:::
```bash
# With npm
npm install @tiptap/extension-task-list @tiptap/extension-task-item
# Or: With Yarn
yarn add @tiptap/extension-task-list @tiptap/extension-task-item
```
## Settings
| Option | Type | Default | Description |
| ------ | ------ | ------- | -------------------------------------------- |
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
*None*
## Source code
[packages/extension-task-item/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-task-item/)
## Usage
<demo name="Nodes/TaskItem" />

33
docs/src/docPages/api/nodes/task-list.md Normal file
View File

@@ -0,0 +1,33 @@
# TaskList
This extension enables you to use task lists in the editor. They are rendered as `<ul data-type="task_list">`. This implementation doesn’t require any framework, it’s using plain JavaScript only.
Type <code>[ ]&nbsp;</code> or <code>[x]&nbsp;</code> at the beginning of a new line and it will magically transform to a task list.
## Installation
::: warning Use with TaskItem
This extension requires the [`TaskItem`](/api/nodes/task-item) extension.
:::
```bash
# with npm
npm install @tiptap/extension-task-list @tiptap/extension-task-item
# with Yarn
yarn add @tiptap/extension-task-list @tiptap/extension-task-item
```
## Settings
| Option | Type | Default | Description |
| ------ | ------ | ------- | -------------------------------------------- |
| class | string | – | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Parameters | Description |
| -------- | ---------- | ------------------- |
| taskList | — | Toggle a task list. |
## Source code
[packages/extension-task-list/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-task-list/)
## Usage
<demo name="Nodes/TaskList" highlight="3-5,17-18,37-38" />

8
docs/src/docPages/api/extensions/text.md → docs/src/docPages/api/nodes/text.md
View File

@@ -2,15 +2,15 @@
**The `Text` extension is required**, at least if you want to work with text of any kind and that’s very likely. This extension is a little bit different, it doesn’t even render HTML. It’s plain text, that’s all.
:::warning Breaking Change from 1.x → 2.x
Tiptap 1 tried to hide that node from you, but it has always been there. You have to explicitly import it from now on (or use `defaultExtensions()`).
tiptap 1 tried to hide that node from you, but it has always been there. You have to explicitly import it from now on (or use `defaultExtensions()`).
:::
## Installation
```bash
# With npm
# with npm
npm install @tiptap/extension-text
# Or: With Yarn
# with Yarn
yarn add @tiptap/extension-text
```
@@ -18,4 +18,4 @@ yarn add @tiptap/extension-text
[packages/extension-text/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text/)
## Usage
<demo name="Extensions/Text" highlight="12,30" />
<demo name="Nodes/Text" highlight="12,30" />

13
docs/src/docPages/api/overview.md
View File

@@ -1,10 +1,13 @@
# Overview
tiptap is a friendly wrapper around [ProseMirror](https://ProseMirror.net).
tiptap is a friendly wrapper around [ProseMirror](https://ProseMirror.net).
ProseMirror works with a strict [Schema](/api/schema), which defines the allowed structure of a document. A document is a tree of headings, paragraphs and others elements, so called nodes. Marks can be attached to a node, e. g. to emphasize part of it. [Commands](/api/commands) change that document programmatically.
### Structure
ProseMirror works with a strict [Schema](/api/schema), which defines the allowed structure of a document. A document is a tree of headings, paragraphs and others elements, so called nodes. Marks can be attached to a node, e. g. to emphasize part of it. [Commands](/api/commands) change that document programmatically.
The document is stored in a state. All changes are applied as transactions to the state. The state has details about the current content, cursor position and selection. You can hook into a few different [events](/api/events), for example to alter transactions before they get applied.
### Content
The document is stored in a state. All changes are applied as transactions to the state. The state has details about the current content, cursor position and selection. You can hook into a few different [events](/api/events), for example to alter transactions before they get applied.
[Extensions](/api/extensions) add functionality like nodes, marks and/or commands to the editor. A huge amount of commands are bound to common [keyboard shortcuts](/api/keyboard-shortcuts).
### Extensions
Extensions add [nodes](/api/nodes), [marks](/api/marks) and/or [functionalities](/api/extensions) to the editor. A lot of those extensions bound their commands to common [keyboard shortcuts](/api/keyboard-shortcuts).
All of those concepts are explained in detail on the following pages.
All those concepts are explained in detail on the following pages.

271
docs/src/docPages/api/schema.md
View File

@@ -1,6 +1,6 @@
# Schema
## Table of Contents
## toc
## Introduction
Unlike many other editors, tiptap is based on a [schema](https://prosemirror.net/docs/guide/#schema) that defines how your content is structured. That enables you to define the kind of nodes that may occur in the document, its attributes and the way they can be nested.
@@ -10,10 +10,10 @@ This schema is *very* strict. You can’t use any HTML element or attribute that
Let me give you one example: If you paste something like `This is <strong>important</strong>` into tiptap, don’t have any extension that handles `strong` tags registered, you’ll only see `This is important` – without the strong tags.
## How a schema looks like
The most simple schema for a typical *ProseMirror* editor is looking something like that:
When you’ll work with the provided extensions only, you don’t have to care that much about the schema. If you’re building your own extensions, it’s probably helpful to understand how the schema works. Let’s look at the most simple schema for a typical ProseMirror editor:
```js
// the underlying ProseMirror schema
{
nodes: {
document: {
@@ -32,58 +32,225 @@ The most simple schema for a typical *ProseMirror* editor is looking something l
}
```
:::warning Out of date
This content is written for tiptap 1 and needs an update.
:::
We register three nodes here. `document`, `paragraph` and `text`. `document` is the root node which allows one or more block nodes as children (`content: 'block+'`). Since `paragraph` is in the group of block nodes (`group: 'block'`) our document can only contain paragraphs. Our paragraphs allow zero or more inline nodes as children (`content: 'inline*'`) so there can only be `text` in it. `parseDOM` defines how a node can be parsed from pasted HTML. `toDOM` defines how it will be rendered in the DOM.
In tiptap we define every node in its own `Extension` class instead. This allows us to split logic per node. Under the hood the schema will be merged together.
In tiptap every node, mark and extension is living in its own file. This allows us to split the logic. Under the hood the whole schema will be merged together:
```js
class Document extends Node {
name = 'document'
topNode = true
// the tiptap schema API
import { createNode } from '@tiptap/core'
schema() {
return {
content: 'block+',
}
}
}
const Document = createNode({
name: 'document',
topNode: true,
content: 'block+',
})
class Paragraph extends Node {
name = 'paragraph'
const Paragraph = createNode({
name: 'paragraph',
group: 'block',
content: 'inline*',
parseHTML() {
return [
{ tag: 'p' },
]
},
renderHTML({ attributes }) {
return ['p', attributes, 0]
},
})
schema() {
return {
content: 'inline*',
group: 'block',
parseDOM: [{ tag: 'p' }],
toDOM: () => ['p', 0],
}
}
}
class Text extends Node {
name = 'text'
schema() {
return {
group: 'inline',
}
}
}
const Text = createNode({
name: 'text',
group: 'inline',
})
```
## Difference between a Node and a Mark
### Parse HTML
*Nodes* are like blocks of content, for example paragraphs, headings, code blocks, blockquotes and many more.
### Render HTML
*Marks* can apply a different style to specific parts of text inside a *Node*. That’s the case for **bold**, *italic* or ~~striked~~ text. [Links](#) are *Marks*, too.
## Nodes and marks
### Differences
Nodes are like blocks of content, for example paragraphs, headings, code blocks, blockquotes and many more.
Marks can be applied to specific parts of a node. That’s the case for **bold**, *italic* or ~~striked~~ text. [Links](#) are marks, too.
### The node schema
#### Content
The content attribute defines exactly what kind of content the node can have. ProseMirror is really strict with that. That means, content which doesn’t fit the schema is thrown away. It expects a name or group as a string. Here are a few examples:
```js
createNode({
// must have one ore more blocks
content: 'block+',
// allows all kinds of 'inline' content (text or hard breaks)
content: 'inline*',
// must not have anything else than 'text'
content: 'text*',
// can have one or more paragraphs, or lists (if lists are used)
content: '(paragraph|list?)+',
})
```
#### Marks
You can define which marks are allowed inside of a node with the `marks` setting of the schema. Add a one or more names or groups of marks, allow all or disallow all marks like this:
```js
createNode({
// allows only the 'bold' mark
marks: 'bold',
// allows only the 'bold' and 'italic' marks
marks: 'bold italic',
// allows all marks
marks: '_',
// disallows all marks
marks: '',
})
```
#### Group
Add this node to a group of extensions, which can be referred to in the [content](#content) attribute of the schema.
```js
createNode({
// add to 'block' group
group: 'block',
// add to 'inline' group
group: 'inline',
// add to 'block' and 'list' group
group: 'block list',
})
```
#### Inline
Nodes can be rendered inline, too. When setting `inline: true` nodes are rendered in line with the text. That’s the case for mentions. The result is more like a mark, but with the functionality of a node. One difference is the resulting JSON document. Multiple marks are applied at once, inline nodes would result in a nested structure.
```js
createNode({
// renders nodes in line with the text, for example
inline: true,
})
```
#### Atom
Nodes with `atom: true` aren’t directly editable and should be treated as a single unit. It’s not so likely to use that in a editor context, but this is how it would look like:
```js
createNode({
atom: true,
})
```
#### Selectable
> Controls whether nodes of this type can be selected as a node selection. Defaults to true for non-text nodes.
```js
createNode({
selectable: true,
})
```
#### Draggable
All nodes can be configured to be draggable (by default they aren’t) with this setting:
```js
createNode({
draggable: true,
})
```
#### Code
Users expect code to behave very differently. For all kind of nodes containing code, you can set `code: true` to take this into account.
```js
createNode({
code: true,
})
```
#### Defining
> Determines whether this node is considered an important parent node during replace operations (such as paste). Non-defining (the default) nodes get dropped when their entire content is replaced, whereas defining nodes persist and wrap the inserted content. Likewise, in inserted content the defining parents of the content are preserved when possible. Typically, non-default-paragraph textblock types, and possibly list items, are marked as defining.
```js
createNode({
defining: true,
})
```
#### Isolating
For nodes that should fence the cursor for regular editing operations like backspacing, for example a TableCell, set `isolating: true`.
```js
createNode({
isolating: true,
})
```
### The mark schema
#### Inclusive
If you don’t want the mark to be active when the cursor is at its end, set inclusive to `false`. For example, that’s how it’s configured for [`Link`](/api/marks/link) marks:
```js
createMark({
inclusive: false,
})
```
#### Excludes
By default all nodes can be applied at the same time. With the excludes attribute you can define which marks must not coexist with the mark. For example, the inline code mark excludes any other mark (bold, italic, and all others).
```js
createMark({
// must not coexist with the bold mark
excludes: 'bold'
// exclude any other mark
excludes: '_',
})
```
#### Group
Add this mark to a group of extensions, which can be referred to in the content attribute of the schema.
```js
createMark({
// add this mark to the 'basic' group
group: 'basic',
// add this mark to the 'basic' and the 'foobar' group
group: 'foobar',
})
```
#### Code
Users expect code to behave very differently. For all kind of marks containing code, you can set `code: true` to take this into account.
```js
createMark({
code: true,
})
```
#### Spanning
By default marks can span multiple nodes when rendered as HTML. Set `spanning: false` to indicate that a mark must not span multiple nodes.
```js
createMark({
spanning: false,
})
```
## Get the underlying ProseMirror schema
There are a few use cases where you need to work with the underlying schema. You’ll need that if you’re using the tiptap collaborative text editing features or if you want to manually render your content as HTML.
### Option 1: With an Editor
@@ -123,23 +290,3 @@ const schema = getSchema([
// add more extensions here
])
```
## Generate HTML from ProseMirror JSON
If you need to render the content on the server side, e. g. for a blog post that was written with tiptap, you’ll probably need a way to do just that without an actual editor instance.
That’s what `generategetHTML()` is for. It’s a utility function that renders HTML without an actual editor instance.
:::warning Work in progress
Currently, that works only in the browser (client side), but we plan to bring this to Node.js (to use it on the server side).
:::
<demo name="Api/Schema/GenerateHtml" highlight="6,29-33"/>
### Converting JSON<>HTML with PHP
We needed to do the same thing in PHP at some point, so we published libraries to convert ProseMirror JSON to HTML and vice-versa:
* [ueberdosis/prosemirror-php](https://github.com/ueberdosis/prosemirror-php) (PHP)
* [ueberdosis/prosemirror-to-html](https://github.com/ueberdosis/prosemirror-to-html) (PHP)
* [ueberdosis/html-to-prosemirror](https://github.com/ueberdosis/html-to-prosemirror) (PHP)