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)

8
docs/src/docPages/examples.md
View File

@@ -1,9 +1,3 @@
# Examples
We put together a few examples to show the capabilities of tiptap, but keep in mind: tiptap is renderless and highly customizable. Everything you see can be changed, modified, combined or remixed. Feel free to copy the code to your project and change it to your liking.
A few examples show what you’d probably expect from a text editor anyway: [Basic](/examples/basic), [Links](/examples/links), [History](/examples/history), [Read-only](/examples/read-only), [Export HTML or JSON](/examples/export-html-or-json).
Some examples show how you can improve the user experience: [Markdown shortcuts](/examples/markdown-shortcuts).
Or they show advanced use cases, like the [Collaborative editing](/examples/collaborative-editing) example, which is basically tiptap in multiplayer mode.
TODO: This page should redirect to [/examples/basic](/examples/basic).

1
docs/src/docPages/examples/basic.md
View File

@@ -1,4 +1,3 @@
# Basic
BUG: Headings can’t be transformed to a bullet or ordered list.
<demo name="Examples/Basic" />

5
docs/src/docPages/examples/collaborative-editing.md
View File

@@ -1,4 +1,9 @@
# Collaborative editing
:::premium Requires Premium Extensions
Using this example in production requires a **tiptap pro** license. [Read more](/sponsor)
:::
This example shows how you can use tiptap to let different users collaboratively work on the same text in real-time.
It connects client with WebRTC and merges changes to the document (no matter where they come from) with the awesome library [Y.js](https://github.com/yjs/yjs) by Kevin Jahns. Be aware that in a real-world scenario you would probably add a server, which is also able to merge changes with Y.js.

3
docs/src/docPages/examples/formatting.md Normal file
View File

@@ -0,0 +1,3 @@
# Formatting
<demo name="Examples/Formatting" />

2
docs/src/docPages/examples/read-only.md
View File

@@ -1,3 +1,3 @@
# Read-only
<demo name="Examples/ReadOnly" highlight="3-6,22,28,40-46" />
<demo name="Examples/ReadOnly" highlight="3-6,22,28,41-47" />

305
docs/src/docPages/guide/build-custom-extensions.md Normal file
View File

@@ -0,0 +1,305 @@
# Build custom extensions
## toc
## Introduction
One of the strength of tiptap is it’s extendability. You don’t depend on the provided extensions, it’s intended to extend the editor to your liking. With custom extensions you can add new content types and new functionalities, on top of what already exists or starting from scratch.
## Option 1: Extend existing extensions
Let’s say you want to change the keyboard shortcuts for the bullet list. You should start by looking at [the source code of the `BulletList` extension](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/index.ts) and find the part you would like to change. In that case, the keyboard shortcut, and just that.
Every extension has an `extend()` method, which takes an object with everything you want to change or add to it. For the bespoken example, your code could like that:
```js
// 1. Import the extension
import BulletList from '@tiptap/extension-bullet-list'
// 2. Overwrite the keyboard shortcuts
const CustomBulletList = BulletList.extend({
addKeyboardShortcuts() {
return {
'Mod-l': () => this.editor.bulletList(),
}
},
})
// 3. Add the custom extension to your editor
new Editor({
extensions: [
CustomBulletList(),
// …
]
})
```
The same applies to every aspect of an existing extension, except to the name. Let’s look at all the things that you can change through the extend method. We focus on one aspect in every example, but you can combine all those examples and change multiple aspects in one `extend()` call too.
### Name
The extension name is used in a whole lot of places and changing it isn’t too easy. If you want to change the name of an existing extension, we would recommended to copy the whole extension and change the name in all occurrences.
The extension name is also part of the JSON. If you [store your content as JSON](/guide/store-content#option-1-json), you need to change the name there too.
### Settings
All settings can be configured through the extension anyway, but if you want to change the default settings, for example to provide a library on top of tiptap for other developers, you can do it like that:
```js
import Heading from '@tiptap/extension-heading'
const CustomHeading = Heading.extend({
defaultOptions: {
levels: [1, 2, 3],
},
})
```
### Schema
tiptap works with a strict schema, which configures how the content can be structured, nested, how it behaves and many more things. You [can change all aspects of the schema](/api/schema) for existing extensions. Let’s walk through a few common use cases.
The default `Blockquote` extension can wrap other nodes, like headings. If you want to allow nothing but paragraphs in your blockquotes, this is how you could achieve it:
```js
// Blockquotes must only include paragraphs
import Blockquote from '@tiptap/extension-blockquote'
const CustomBlockquote = Blockquote.extend({
content: 'paragraph*',
})
```
The schema even allows to make your nodes draggable, that’s what the `draggable` option is for, which defaults to `false`.
```js
// Draggable paragraphs
import Paragraph from '@tiptap/extension-paragraph'
const CustomParagraph = Paragraph.extend({
draggable: true,
})
```
That’s just two tiny examples, but [the underlying ProseMirror schema](https://prosemirror.net/docs/ref/#model.SchemaSpec) is really powerful. You should definitely read the documentation to understand all the nifty details.
### Attributes
You can use attributes to store additional information in the content. Let’s say you want to extend the default paragraph extension to enable paragraphs to have different colors:
```js
const CustomParagraph = Paragraph.extend({
addAttributes() {
// Return an object with attribute configuration
return {
color: {
default: 'pink',
},
},
},
})
// Result:
// <p data-color="pink">Example Text</p>
```
That’s already enough to tell tiptap about the new attribute, and set `'pink'` as the default value. All attributes will be rendered as a data-attributes by default, and parsed as data-attributes from the content.
Let’s stick with the color example and assume you’ll want to add an inline style to actually color the text. With the `renderHTML` function you can return HTML attributes which will be rendered in the output.
This examples adds a style HTML attribute based on the value of color:
```js
const CustomParagraph = Paragraph.extend({
addAttributes() {
return {
color: {
default: null,
// Take the attribute values
renderHTML: attributes => {
// … and return an object with HTML attributes.
return {
style: `color: ${attributes.color}`,
}
},
},
}
},
})
// Result:
// <p data-color="pink" style="color: pink">Example Text</p>
```
You can also control how the attribute is parsed from the HTML. Let’s say you want to store the color in an attribute called `data-my-fancy-color-attribute`. Legit, right? Anyway, here’s how you would do that:
```js
const CustomParagraph = Paragraph.extend({
addAttributes() {
return {
color: {
default: null,
// Customize the HTML parsing (for example, to load the initial content)
parseHTML: element => {
return {
color: element.getAttribute('data-my-fancy-color-attribute'),
}
},
// … and customize the HTML rendering.
renderHTML: attributes => {
return {
'data-my-fancy-color-attribute': atttributes.color,
style: `color: ${attributes.color}`,
}
},
},
}
},
})
// Result:
// <p data-my-fancy-color-attribute="pink" style="color: pink">Example Text</p>
```
### Global Attributes
Attributes can be applied to multiple extensions at once. That’s useful for text alignment, line height, color, font family, and other styling related attributes.
Take a closer look at [the full source code](https://github.com/ueberdosis/tiptap-next/tree/main/packages/extension-text-align) of the [`TextAlign`](/api/extensions/text-align) extension to see a more complex example. But here is how it works in a nutshell:
```js
import { createExtension } from '@tiptap/core'
const TextAlign = createExtension({
addGlobalAttributes() {
return [
{
// Extend the following extensions
types: [
'heading',
'paragraph',
],
// … with those attributes
attributes: {
textAlign: {
default: 'left',
renderHTML: attributes => ({
style: `text-align: ${attributes.textAlign}`,
}),
parseHTML: element => ({
textAlign: element.style.textAlign || 'left',
}),
},
},
},
]
},
})
```
### Render HTML
With the `renderHTML` function you can control how an extension is rendered to HTML. We pass an attributes object to it, with all local attributes, global attributes, and configured CSS classes. Here is an example from the `Bold` extension:
```js
renderHTML({ attributes }) {
return ['strong', attributes, 0]
},
```
The first value in the array should be the name of HTML tag. If the second element is an object, it’s interpreted as a set of attributes. Any elements after that are rendered as children.
The number zero (representing a hole) is used to indicate where the content should be inserted. Let’s look at the rendering of the `CodeBlock` extension with two nested tags:
```js
renderHTML({ attributes }) {
return ['pre', ['code', attributes, 0]]
},
```
If you want to add some specific attributes there, import the `mergeAttributes` helper from `@tiptap/core`:
```js
renderHTML({ attributes }) {
return ['a', mergeAttributes(attributes, { rel: this.options.rel }), 0]
},
```
### Parse HTML
> Associates DOM parser information with this mark (see the corresponding node spec field). The mark field in the rules is implied.
### Commands
```js
import Paragraph from '@tiptap/extension-paragraph'
const CustomParagraph = Paragraph.extend({
addCommands() {
return {
paragraph: () => ({ commands }) => {
return commands.toggleBlockType('paragraph', 'paragraph')
},
}
},
})
```
### Keyboard shortcuts
Most core extensions come with sensible keyboard shortcut defaults. Depending on what you want to build, you’ll likely want to change them though. With the `addKeyboardShortcuts()` method you can overwrite the predefined shortcut map:
```js
// Change the bullet list keyboard shortcut
import BulletList from '@tiptap/extension-bullet-list'
const CustomBulletList = BulletList.extend({
addKeyboardShortcuts() {
return {
'Mod-l': () => this.editor.bulletList(),
}
},
})
```
### Input rules
```js
// Use the ~single tilde~ markdown shortcut
import Strike from '@tiptap/extension-strike'
import { markInputRule } from '@tiptap/core'
const inputRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/gm
const CustomStrike = Strike.extend({
addInputRules() {
return [
markInputRule(inputRegex, this.type),
]
},
})
```
### Paste rules
```js
// Overwrite the underline regex for pasted text
import Underline from '@tiptap/extension-underline'
import { markPasteRule } from '@tiptap/core'
const pasteRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/gm
const CustomUnderline = Underline.extend({
addPasteRules() {
return [
markPasteRule(inputRegex, this.type),
]
},
})
```
### Node views
## Option 2: Start from scratch
### Read the documentation
Although tiptap tries to hide most of the complexity of ProseMirror, it’s built on top of its APIs and we recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/) for advanced usage. You’ll have a better understanding of how everything works under the hood and get more familiar with many terms and jargon used by tiptap.
### Have a look at existing extensions
### Get started
### Ask questions
### Share your extension

7
docs/src/docPages/guide/collaborative-editing.md
View File

@@ -1,9 +1,12 @@
# Collaborative editing
## Table of Contents
:::premium Requires Premium Extensions
Using the collaborative editing in production requires a **tiptap pro** license. [Read more](/sponsor)
:::
## toc
## Introduction
Collaborative editing allows multiple users to work on the same text document in real-time. It’s a complex topic that you should be aware before adding it blindly to you app. No worries though, here is everything you need to know.
## Configure collaboration

2
docs/src/docPages/guide/configuration.md
View File

@@ -1,6 +1,6 @@
# Configuration
## Table of Contents
## toc
## Introduction
tiptap is all about customization. There are a ton of options to configure the behavior and functionality of the editor. Most of those settings can be set before creating the Editor. Give tiptap a JSON with all the settings you would like to overwrite.

4
docs/src/docPages/guide/build-your-editor.md → docs/src/docPages/guide/create-your-editor.md
View File

@@ -1,6 +1,6 @@
# Build your editor
## Table of Contents
## toc
## Introduction
In its simplest version tiptap comes very raw. There is no menu, no buttons, no styling. That’s intended. See tiptap as your building blocks to build exactly the editor you would like to have.
@@ -18,7 +18,7 @@ You might wonder what features tiptap supports out of the box. In the above exam
* [List of available commands](/api/commands)
## Configure extensions
You are free to choose which parts of tiptap you want to use. Tiptap has support for different nodes (paragraphs, blockquotes, tables and many more) and different marks (bold, italic, links). If you want to explicitly configure what kind of nodes and marks are allowed and which are not allowed, you can configure those.
You are free to choose which parts of tiptap you want to use. tiptap has support for different nodes (paragraphs, blockquotes, tables and many more) and different marks (bold, italic, links). If you want to explicitly configure what kind of nodes and marks are allowed and which are not allowed, you can configure those.
Note that `Document`, `Paragraph` and `Text` are required. Otherwise you won’t be able to add any plain text.

142
docs/src/docPages/guide/custom-extensions.md
View File

@@ -1,142 +0,0 @@
# Custom Extensions
## Table of Contents
## Introduction
One of the strength of tiptap is it’s extendability. You don’t depend on the provided extensions, it’s intended to extend the editor to your liking. With custom extensions you can add new content types and new functionalities, on top of what already exists or on top of that.
## Option 1: Change defaults
Let’s say you want to change the keyboard shortcuts for the bullet list. You should start by looking at [the source code of the `BulletList` extension](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/index.ts) and find the default you’d like to change. In that case, the keyboard shortcut, and just that.
```js
// 1. Import the extension
import BulletList from '@tiptap/extension-bullet-list'
// 2. Overwrite the keyboard shortcuts
const CustomBulletList = BulletList()
.keys(({ editor }) => ({
'Mod-l': () => editor.bulletList(),
}))
.create() // Don’t forget that!
// 3. Add the custom extension to your editor
new Editor({
extensions: [
CustomBulletList(),
// …
]
})
```
You can overwrite every aspect of an existing extension:
### Name
```js
import Document from '@tiptap/extension-document'
const CustomDocument = Document()
.name('doc')
.create()
```
### Settings
```js
import Heading from '@tiptap/extension-heading'
const CustomHeading = Heading()
.defaults({
levels: [1, 2, 3],
class: 'my-custom-heading',
})
.create()
```
### Schema
```js
import Code from '@tiptap/extension-code'
const CustomCode = Code()
.schema(() => ({
excludes: '_',
parseDOM: [
{ tag: 'code' },
],
toDOM: () => ['code', { 'data-attribute': 'foobar' }, 0],
}))
.create()
```
### Commands
```js
import Paragraph from '@tiptap/extension-paragraph'
const CustomParagraph = Paragraph()
.commands(() => ({
paragraph: () => ({ commands }) => {
return commands.toggleBlockType(name, 'paragraph')
},
}))
.create()
```
### Keyboard shortcuts
```js
import BulletList from '@tiptap/extension-bullet-list'
const CustomBulletList = BulletList()
.keys(({ editor }) => ({
'Mod-l': () => editor.bulletList(),
}))
.create()
```
### Input rules
```js
import Strike from '@tiptap/extension-strike'
import { markInputRule } from '@tiptap/core'
const inputRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/gm
const CustomStrike = Strike()
.inputRules(({ type }) => [
markInputRule(inputRegex, type),
])
.create()
```
### Paste rules
```js
import Underline from '@tiptap/extension-underline'
import { markPasteRule } from '@tiptap/core'
const pasteRegex = /(?:^|\s)((?:~)((?:[^~]+))(?:~))$/gm
const CustomUnderline = Underline()
.pasteRules(({ type }) => [
markPasteRule(pasteRegex, type),
])
.create()
```
## Option 2: Extend existing extensions
## Option 3: Start from scratch
### 1. Read the documentation
Although tiptap tries to hide most of the complexity of ProseMirror, it’s built on top of its APIs and we recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/) for advanced usage. You’ll have a better understanding of how everything works under the hood and get more familiar with many terms and jargon used by tiptap.
### 2. Have a look at existing extensions
### 3. Get started
### 4. Ask questions
### 5. Publish a community extension

30
docs/src/docPages/guide/custom-styling.md
View File

@@ -1,9 +1,9 @@
# Custom styling
## Table of Contents
## toc
## Introduction
Tiptap is renderless, that doesn’t mean there is no styling provided. You can decided how your editor should look like.
tiptap is renderless, that doesn’t mean there is no styling provided. You can decided how your editor should look like.
## Option 1: Style the plain HTML
The whole editor is rendered inside of a container with the class `.ProseMirror`. You can use that to scope your styling to the editor content:
@@ -28,15 +28,21 @@ p {
## Option 2: Add custom classes
Most extensions have a `class` option, which you can use to add a custom CSS class to the HTML tag.
Most extensions allow you to add attributes to the rendered HTML through the `attributes` configuration. You can use that to add a custom class (or any other attribute):
```js
new Editor({
extensions: [
Document(),
Paragraph({
class: 'my-custom-paragraph',
attributes: {
class: 'my-custom-paragraph',
},
}),
Heading({
class: 'my-custom-heading',
attributes: {
class: 'my-custom-heading',
},
}),
Text(),
]
@@ -50,17 +56,21 @@ The rendered HTML will look like that:
<p class="my-custom-paragraph">Wow, that’s really custom.</p>
```
If there are already classes defined by the extensions, your classes will be added.
## Option 3: Customize the HTML
You can even customize the markup for every extension. This will make a custom bold extension that doesn’t render a `<strong>` tag, but a `<b>` tag:
```js
import Bold from '@tiptap/extension-bold'
const CustomBold = Bold
.schema(() => ({
toDOM: () => ['b', 0],
}))
.create()
const CustomBold = Bold.extend({
renderHTML({ attributes }) {
// Original:
// return ['strong', attributes, 0]
return ['b', attributes, 0]
},
})
new Editor({
extensions: [
@@ -70,4 +80,4 @@ new Editor({
})
```
You should put your custom extensions in separate files though, but I think you’ve got the idea.
You should put your custom extensions in separate files though, but I think you got the idea.

4
docs/src/docPages/guide/getting-started.md
View File

@@ -1,6 +1,6 @@
# Getting started
## Table of Contents
## toc
## Introduction
tiptap is framework-agnostic and works with Vue.js and React. It even works with plain JavaScript, if that’s your thing. To keep everything as small as possible, we put the code to use tiptap with those frameworks in different packages.
@@ -19,7 +19,7 @@ yarn add @tiptap/vue @tiptap/vue-starter-kit
The `@tiptap/vue-starter-kit` includes a few basics you would probably need anyway. Cool, you have got everything in place to set up tiptap! 🙌
## 2. Create a new component
Create a new Vue component (you can call it `<Tiptap />`) and add the following content. This is the fastest way to get tiptap up and running with Vue.js. It will give you a very basic version of tiptap, without any buttons. No worries, you will be able to add more functionality soon.
Create a new Vue component (you can call it `<tiptap />`) and add the following content. This is the fastest way to get tiptap up and running with Vue.js. It will give you a very basic version of tiptap, without any buttons. No worries, you will be able to add more functionality soon.
<demo name="Guide/GettingStarted" />

15
docs/src/docPages/guide/store-content.md
View File

@@ -1,6 +1,6 @@
# Store content
## Table of Contents
## toc
## Introduction
You can store your content as a JSON object or as a good old HTML string. Both work fine. And of course, you can pass both formats to the editor to restore your content.
@@ -85,6 +85,17 @@ Unfortunately, **tiptap doesn’t support Markdown as an input or output format*
You should really consider to work with HTML or JSON to store your content, they are perfectly fine for most use cases.
If you still think you need Markdown, [Nextcloud Text](https://github.com/nextcloud/text) uses tiptap to work with Markdown. Their code is open source, so maybe you can learn from them.
If you still think you need Markdown, [Nextcloud Text](https://github.com/nextcloud/text) uses tiptap 1 to work with Markdown. Their code is open source, so maybe you can learn from them.
That said, tiptap **does** support Markdown shortcuts to format your content. Try typing `**two asterisks**` to make your text bold for example.
## Generate HTML from ProseMirror JSON
If you need to render the content on the server side, for example to render a blog post which was written with tiptap, you’ll probably need a way to do just that without an actual editor instance.
That’s what `generateHTML()` is for. It’s a utility function that renders HTML without an actual editor instance.
:::info Browser-only rendering
Import a lightweight implementation from `@tiptap/core` if you’re using the function in a browser context only.
:::
<demo name="Api/Schema/GenerateHTML" highlight="6,29-33"/>

21
docs/src/docPages/introduction.md
View File

@@ -1,15 +1,17 @@
:::warning Don’t try this at home
This version of tiptap is not production-ready, don’t use it anywhere.
:::error Don’t try this at home
Nothing here is production-ready, don’t use it anywhere.
:::
# Introduction
[![Version](https://img.shields.io/npm/v/@tiptap/core.svg?label=version)](https://www.npmjs.com/package/@tiptap/core)
[![Downloads](https://img.shields.io/npm/dm/@tiptap/core.svg)](https://npmcharts.com/compare/@tiptap/core?minimal=true)
[![License](https://img.shields.io/npm/l/@tiptap/core.svg)](https://www.npmjs.com/package/@tiptap/core)
<!-- [![Version](https://img.shields.io/npm/v/@tiptap/core.svg?label=version)](https://www.npmjs.com/package/@tiptap/core) -->
<!-- [![Downloads](https://img.shields.io/npm/dm/@tiptap/core.svg)](https://npmcharts.com/compare/@tiptap/core?minimal=true) -->
<!-- [![License](https://img.shields.io/npm/l/@tiptap/core.svg)](https://www.npmjs.com/package/@tiptap/core) -->
<!-- [![Filesize](https://img.badgesize.io/https://unpkg.com/tiptap/dist/tiptap.min.js?compression=gzip&label=size&colorB=000000)](https://www.npmjs.com/package/tiptap) -->
<!-- [![Build Status](https://github.com/ueberdosis/tiptap-next/workflows/build/badge.svg)](https://github.com/ueberdosis/tiptap-next/actions) -->
[![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis)
tiptap is a renderless wrapper around [ProseMirror](https://ProseMirror.net) – a toolkit for building rich-text editors that is already in use at many well-known companies such as *New York Times*, *The Guardian* or *Atlassian*.
tiptap is a renderless wrapper around [ProseMirror](https://ProseMirror.net) – a toolkit for building rich-text WYSIWYG editors, which is already in use at many well-known companies such as *New York Times*, *The Guardian* or *Atlassian*.
Although tiptap tries to hide most of the complexity of ProseMirror, it’s built on top of its APIs and we recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/) for advanced usage. You’ll have a better understanding of how everything works under the hood and get more familiar with many terms and jargon used by tiptap.
@@ -17,9 +19,9 @@ Although tiptap tries to hide most of the complexity of ProseMirror, it’s buil
**Renderless.** We don’t tell you what a menu should look like or where it should be rendered in the DOM. That’s why tiptap is renderless and comes without any CSS. You are in full control over markup and styling.
**Framework-agnostic.** We don’t care what framework you use. Tiptap is ready to be used with plain JavaScript or Vue.js. That makes it even possible to write a renderer for React, Svelte and others.
**Framework-agnostic.** We don’t care what framework you use. tiptap is ready to be used with plain JavaScript or Vue.js. That makes it even possible to write a renderer for React, Svelte and others.
**TypeScript.** Tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE supports that), helps to find bugs early and makes it possible to generate [a complete API documentation](#) on top of the extensive human written documentation.
**TypeScript.** tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE supports that), helps to find bugs early and makes it possible to generate [a complete API documentation](#) on top of the extensive human written documentation.
## Who uses tiptap?
- [GitLab](https://gitlab.com)
@@ -29,3 +31,6 @@ Although tiptap tries to hide most of the complexity of ProseMirror, it’s buil
- [Directus CMS](https://directus.io)
- [Nextcloud](https://apps.nextcloud.com/apps/text)
- [and many more →](https://github.com/ueberdosis/tiptap/network/dependents?package_id=UGFja2FnZS0xMzE5OTg0ODc%3D)
## License
tiptap is licensed under MIT, so you’re free to whatever you want. Anyway, we kindly ask you to [become a sponsor](https://github.com/sponsors/ueberdosis) on GitHub to fund the development, maintenance and support of tiptap.

26
docs/src/docPages/open.md Normal file
View File

@@ -0,0 +1,26 @@
# Monthly reports
## October 2020
* Writing extensions for tiptap 2
* 25 sponsors, $423/month
* 102 hours, $7,140 development costs (at $70/hour)
* Sponsored @calebporzio with $99
* **Total -$6,816**
## September 2020
* Developing the API of tiptap 2, writing the documentation
* 125 hours, $8,750 development costs (at $70/hour)
* Sponsored @calebporzio with $99
* **Total -$8,849**
## August 2020
* Setting up tiptap 2
* 56 hours, $3,920 development costs (at $70/hour)
* Sponsored @calebporzio with $99
* **Total -$4,019**
## All time
* **Total -$19.684**

9
docs/src/docPages/overview/contributing.md
View File

@@ -1,13 +1,14 @@
# Contributing
## Table of Contents
## toc
## Introduction
Tiptap would be nothing without its lively community. Contributions have always been and will always be welcome. Here is a little bit you should know, before you send your contribution:
tiptap would be nothing without its lively community. Contributions have always been and will always be welcome. Here is a little bit you should know, before you send your contribution:
## Welcome examples
* Improve the documentation, e. g. fix a typo, add a section
* New features for existing extensions, e. g. a new option
* Failing regression tests as bug reports
* Documentation improvements, e. g. fix a typo, add a section
* New features for existing extensions, e. g. a new configureable option
* New extensions, which don’t require changes to the core or other core extensions
* Well explained, non-breaking changes to the core

17
docs/src/docPages/overview/installation.md
View File

@@ -1,6 +1,6 @@
# Installation
## Table of Contents
## toc
## Introduction
You’re free to use tiptap with the framework of your choice. Depending on what you want to do, there are a few different ways to install tiptap in your project. Choose the way that fits your workflow.
@@ -9,10 +9,10 @@ You’re free to use tiptap with the framework of your choice. Depending on what
Use tiptap with vanilla JavaScript for a very lightweight and raw experience. If you feel like it, you can even use it to connect tiptap with other frameworks not mentioned here.
```bash
# With npm
# with npm
npm install @tiptap/core @tiptap/starter-kit
# Or: With Yarn
# with Yarn
yarn add @tiptap/core @tiptap/starter-kit
```
@@ -33,10 +33,10 @@ new Editor({
To use tiptap with Vue.js (and tools that are based on Vue.js) install tiptap together with the Vue.js adapter in your project. We even prepared a Vue.js starter kit, which gives you a good headstart.
```bash
# With npm
# with npm
npm install @tiptap/core @tiptap/vue @tiptap/vue-starter-kit
# Or: With Yarn
# with Yarn
yarn add @tiptap/core @tiptap/vue @tiptap/vue-starter-kit
```
@@ -44,9 +44,10 @@ Create a new component and add the following content to get a basic version of t
<demo name="Overview/Installation" />
::: warning Nuxt.js
If you use Nuxt.js, note that tiptap needs to run in the client, not on the server. It’s required to wrap the editor in a `<client-only>` tag.
:::
### Nuxt.js
Note that tiptap needs to run in the client, not on the server. It’s required to wrap the editor in a `<client-only>` tag.
[Read more](https://nuxtjs.org/api/components-client-only)
<!-- ## Option 3: CodeSandbox

85
docs/src/docPages/overview/upgrade-guide.md
View File

@@ -1,11 +1,11 @@
# Upgrade Guide
## Table of Contents
## toc
## Reasons to upgrade to tiptap 2.x
Yes, it’s tedious work to upgrade your favorite text editor to a new API, but we made sure you’ve got enough reasons to upgrade to the newest version
* Autocomplete in your IDE (thanks to TypeScript)
* Autocompletion in your IDE (thanks to TypeScript)
* Amazing documentation with 100+ pages
* Active development, new features in the making
* Tons of new extensions planned
@@ -14,8 +14,11 @@ Yes, it’s tedious work to upgrade your favorite text editor to a new API, but
## Upgrading from 1.x to 2.x
The new API will look pretty familiar too you, but there are a ton of changes though. To make the upgrade a little bit easier, here is everything you need to know:
### Upgrade to Vue.js 3
…
### Explicitly register the Document, Text and Paragraph extensions
Tiptap 1 tried to hide a few required extensions from you with the default setting `useBuiltInExtensions: true`. That setting has been removed and you’re required to import all extensions. Be sure to explicitly import at least the [Document](/api/extensions/document), [Paragraph](/api/extensions/paragraph) and [Text](/api/extensions/text) extensions.
tiptap 1 tried to hide a few required extensions from you with the default setting `useBuiltInExtensions: true`. That setting has been removed and you’re required to import all extensions. Be sure to explicitly import at least the [Document](/api/nodes/document), [Paragraph](/api/nodes/paragraph) and [Text](/api/nodes/text) extensions.
```js
import Document from '@tiptap/extension-document'
@@ -24,68 +27,58 @@ import Text from '@tiptap/extension-text'
new Editor({
extensions: [
Document(),
Paragraph(),
Text(),
// all your other extensions
Document(),
Paragraph(),
Text(),
// all your other extensions
]
})
```
### New document type
**We renamed the default `Document` type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name.
```js
import Document from '@tiptap/extension-document'
const CustomDocument = Document.name('doc').create()
new Editor({
extensions: [
CustomDocument(),
// …
]
})
```
~~**We renamed the default `Document` type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name.~~
### New extension API
In case you’ve built some custom extensions for your project, you’re required to rewrite them to fit the new API. No worries, you can keep a lot of your work though. The `schema`, `commands`, `keys`, `inputRules` and `pasteRules` all work like they did before. It’s just different how you register them.
```js
import { Node } from '@tiptap/core'
import { createNode } from '@tiptap/core'
const CustomExtension = new Node()
.name('custom_extension')
.defaults({
// …
})
.schema(() => ({
// …
}))
.commands(({ editor, name }) => ({
// …
}))
.keys(({ editor }) => ({
// …
}))
.inputRules(({ type }) => [
// …
])
.pasteRules(({ type }) => [
// …
])
.create()
const CustomExtension = createNode({
name: 'custom_extension'
defaultOptions: {
…
},
addAttributes() {
…
},
parseHTML() {
…
},
renderHTML({ node, attributes }) {
…
},
addCommands() {
…
},
addKeyboardShortcuts() {
…
},
addInputRules() {
…
},
// and more …
})
```
Don’t forget to call `create()` in the end! Read more about [all the nifty details building custom extensions](/guide/custom-extensions) in our guide.
Don’t forget to call `create()` in the end! Read more about [all the nifty details building custom extensions](/guide/build-custom-extensions) in our guide.
### Renamed API methods
[We renamed a lot of commands](/api/commands), hopefully you can migrate to the new API with search & replace. Here is a list of what changed:
| Old method name | New method name |
| --------------- | --------------- |
| ~~`getHTML`~~ | `html` |
| ~~`getJSON`~~ | `json` |
| ~~`…`~~ | `…` |
### Commands can be chained now

23
docs/src/docPages/sponsor.md Normal file
View File

@@ -0,0 +1,23 @@
# Become a sponsor
To deliver you a top-notch developer experience and user experience, we put hundreds of hours of unpaid work into tiptap. Your funding helps us to make this work more and more financially sustainable. This enables us, to provide helpful support, maintain all our packages, keep everything up to date, and develop new features and extensions for tiptap.
If you’re using tiptap in a commercial project or just want to give back to the open source community, you can [sponsor us on GitHub](https://github.com/sponsors/ueberdosis).
## Your benefits as a sponsor
* Give back to the open source community
* Get early access to the tiptap 2 repository
* Your issues and pull requests get a `sponsor 💖` label
* Get a sponsor badge in all your comments on GitHub
* Show the support in your GitHub profile
* Receive monthly reports related to our open source work
Does that sound good? [Sponsor us on GitHub!](https://github.com/sponsors/ueberdosis)
## I can’t use GitHub.
If you’re a company, don’t want to use GitHub, don’t have a credit card or want a proper invoice form us, just reach out to us at [hans.pagel@ueber.io](mailto:hans.pagel@ueber.io).
## I want consulting.
We don’t do any calls, consulting or personal support. If you have an issue, a question, want to talk something through or anything else, please use GitHub issues, to keep everything accessible for the whole community.
## Can we have a call?
Nope, we are big fans of asynchronous communication. If you really need to reach out in private, send us an email to [hans.pagel@ueber.io](mailto:hans.pagel@ueber.io), but don’t expect technical email support.