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

Merge branch 'main' of https://github.com/ueberdosis/tiptap-next into feature/improve-command-chaining

Browse Source
This commit is contained in:
Philipp Kühn
2020-09-22 20:09:22 +02:00
parent 25a79b4aea 51af4b696b
commit 7f9bb9f1d1
30 changed files with 229 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@@ -10,6 +10,17 @@ A renderless and extendable rich-text editor for [Vue.js](https://github.com/vue
[![Build Status](https://github.com/ueberdosis/tiptap-next/workflows/build/badge.svg)](https://github.com/ueberdosis/tiptap-next/actions) [![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) [![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis)
## Roadmap
- [x] Proof of concept
- [ ] Building out the editor
- [ ] Adding a bunch of extensions
- [ ] Creating a few examples
- [ ] Giving sponsors access to gather feedback
- [ ] Incorporate feedback
- [ ] Publicly release version 2.0-beta
- [ ] Squash bugs, build more extensions
- [ ] Release version 2.0
## Why we built tiptap ## Why we built tiptap
We were looking for a text editor for [Vue.js](https://github.com/vuejs/vue) and found some solutions that didn’t really satisfy me. The editor should be easy to extend and not based on old dependencies such as jQuery. For React there is already a great editor called [Slate.js](https://github.com/ianstormtaylor/slate), which impresses with its modularity. I came across [ProseMirror](https://github.com/prosemirror) and decided to build on it. ProseMirror is a toolkit for building rich-text editors that are already in use at many well-known companies such as *Atlassian* or *New York Times*. We were looking for a text editor for [Vue.js](https://github.com/vuejs/vue) and found some solutions that didn’t really satisfy me. The editor should be easy to extend and not based on old dependencies such as jQuery. For React there is already a great editor called [Slate.js](https://github.com/ianstormtaylor/slate), which impresses with its modularity. I came across [ProseMirror](https://github.com/prosemirror) and decided to build on it. ProseMirror is a toolkit for building rich-text editors that are already in use at many well-known companies such as *Atlassian* or *New York Times*.

8
docs/src/demos/Extensions/CodeBlock/index.vue
View File

@@ -36,7 +36,9 @@ export default {
CodeBlock(), CodeBlock(),
], ],
content: ` content: `
<p>That’s a boring paragraph followed by a fenced code block:</p> <p>
That’s a boring paragraph followed by a fenced code block:
</p>
<pre><code>for (var i=1; i <= 20; i++) <pre><code>for (var i=1; i <= 20; i++)
{ {
if (i % 15 == 0) if (i % 15 == 0)
@@ -48,7 +50,9 @@ export default {
else else
console.log(i); console.log(i);
}</code></pre> }</code></pre>
<p>Press Command/Ctrl + Enter to leave the fenced code block and continue typing in boring paragraphs. <p>
Press Command/Ctrl + Enter to leave the fenced code block and continue typing in boring paragraphs.
</p>
`, `,
}) })
}, },

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

@@ -1,25 +1,28 @@
# Editor # Editor
:::warning Out of date
This content is written for tiptap 1 and needs an update.
:::
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. 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.
## Editor Properties ## Settings
| Property | Type | Default | Description | All of the listed settings can be set during initialization, read and updated during runtime.
| ---------------------- | :--------------: | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. | | Setting | Type | Default | Description |
| `editorProps` | `Object` | `{}` | A list of [Prosemirror editorProps](https://prosemirror.net/docs/ref/#view.EditorProps). | | ------------------ | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `editable` | `Boolean` | `true` | When set to `false` the editor is read-only. | | `autoFocus` | `Boolean` | `false` | Focus the editor on init. |
| `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. |
| `extensions` | `Array` | `[]` | A list of extensions used, by the editor. This can be `Nodes`, `Marks` or `Plugins`. | | `dropCursor` | `Object` | `{}` | Config for `prosemirror-dropcursor`. |
| `useBuiltInExtensions` | `Boolean` | `true` | By default tiptap adds a `Doc`, `Paragraph` and `Text` node to the Prosemirror schema. | | `editable` | `Boolean` | `true` | When set to `false` the editor is read-only. |
| `dropCursor` | `Object` | `{}` | Config for `prosemirror-dropcursor`. | | `editorProps` | `Object` | `{}` | A list of [Prosemirror editorProps](https://prosemirror.net/docs/ref/#view.EditorProps). |
| `enableDropCursor` | `Boolean` | `true` | Option to enable / disable the dropCursor plugin. | | `enableDropCursor` | `Boolean` | `true` | Option to enable / disable the dropCursor plugin. |
| `enableGapCursor` | `Boolean` | `true` | Option to enable / disable the gapCursor plugin. | | `enableGapCursor` | `Boolean` | `true` | Option to enable / disable the gapCursor plugin. |
| `parseOptions` | `Object` | `{}` | A list of [Prosemirror parseOptions](https://prosemirror.net/docs/ref/#model.ParseOptions). | | `extensions` | `Array` | `[]` | A list of extensions used, by the editor. This can be `Nodes`, `Marks` or `Plugins`. |
| `onInit` | `Function` | `undefined` | This will return an Object with the current `state` and `view` of Prosemirror on init. | | `parseOptions` | `Object` | `{}` | A list of [Prosemirror parseOptions](https://prosemirror.net/docs/ref/#model.ParseOptions). |
| `onFocus` | `Function` | `undefined` | This will return an Object with the `event` and current `state` and `view` of Prosemirror on focus. |
| `onBlur` | `Function` | `undefined` | This will return an Object with the `event` and current `state` and `view` of Prosemirror on blur. | ## Hooks
| `onUpdate` | `Function` | `undefined` | This will return an Object with the current `state` of Prosemirror, a `getJSON()` and `getHTML()` function and the `transaction` on every change. | The editor provides a few hooks to react to specific [events](/api/events). Pass a function that get’s called in case of those events.
| Hook | Type | Default | Description |
| ---------- | ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `onBlur` | `Function` | `undefined` | This will return an Object with the `event` and current `state` and `view` of Prosemirror on blur. |
| `onFocus` | `Function` | `undefined` | This will return an Object with the `event` and current `state` and `view` of Prosemirror on focus. |
| `onInit` | `Function` | `undefined` | This will return an Object with the current `state` and `view` of Prosemirror on init. |
| `onUpdate` | `Function` | `undefined` | This will return an Object with the current `state` of Prosemirror, a `json()` and `html()` function and the `transaction` on every change. |

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

@@ -11,9 +11,9 @@ const editor = new Editor({
onInit: () => { onInit: () => {
// editor is initialized // editor is initialized
}, },
onUpdate: ({ getHTML }) => { onUpdate: ({ html }) => {
// get new content on update // get new content on update
const newContent = getHTML() const newContent = html()
}, },
}) })
``` ```
@@ -27,8 +27,8 @@ editor.on('init', () => {
// editor is initialized // editor is initialized
}) })
editor.on('update', ({ getHTML }) => { editor.on('update', ({ html }) => {
// get new content on update // get new content on update
const newContent = getHTML() const newContent = html()
}) })
``` ```

13
docs/src/docPages/api/extensions/blockquote.md
View File

@@ -1,7 +1,16 @@
# Blockquote # Blockquote
The Blockquote extension enables you to use the `<blockquote>` HTML tag in the editor. This is great – you might have guessed – to use quotes in the editor. The Blockquote extension enables you to use the `<blockquote>` HTML tag in the editor. This is great – you might have guessed – to use quotes in the editor.
Type `> ​` at the beginning of a new line and it will be magically transformed to a blockquote. Type `> ​` at the beginning of a new line and it will magically transform to a blockquote.
## Installation
```bash
# With npm
npm install @tiptap/extension-blockquote
# Or: With Yarn
yarn add @tiptap/extension-blockquote
```
## Options ## Options
| Option | Type | Default | Description | | Option | Type | Default | Description |
@@ -17,7 +26,7 @@ Type `> ​` at the beginning of a new line and it will be magically transformed
* Windows & Linux: `Control` + `Shift` + `9` * Windows & Linux: `Control` + `Shift` + `9`
* macOS: `Command` + `Shift` + `9` * macOS: `Command` + `Shift` + `9`
## Source Code ## Source code
[packages/extension-blockquote/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-blockquote/) [packages/extension-blockquote/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-blockquote/)
## Usage ## Usage

4
docs/src/docPages/api/extensions/bold.md
View File

@@ -1,7 +1,7 @@
# Bold # Bold
Use this extension to render text in **bold**. If you pass `<strong>`, `<b>` tags, or text with inline `style` attributes setting the `font-weight` CSS rule in the editor’s initial content, they all will be rendered accordingly. Use this extension to render text in **bold**. If you pass `<strong>`, `<b>` tags, or text with inline `style` attributes setting the `font-weight` CSS rule in the editor’s initial content, they all will be rendered accordingly.
Type `**two asterisks**` or `__two underlines__` and it will be magically transformed to **bold** text while you type. Type `**two asterisks**` or `__two underlines__` and it will magically transform to **bold** text while you type.
::: warning Restrictions ::: warning Restrictions
The extension will generate the corresponding `<strong>` HTML tags when reading contents of the `Editor` instance. All text marked bold, regardless of the method will be normalized to `<strong>` HTML tags. The extension will generate the corresponding `<strong>` HTML tags when reading contents of the `Editor` instance. All text marked bold, regardless of the method will be normalized to `<strong>` HTML tags.
@@ -21,7 +21,7 @@ The extension will generate the corresponding `<strong>` HTML tags when reading
* Windows & Linux: `Control` + `B` * Windows & Linux: `Control` + `B`
* macOS: `Command` + `B` * macOS: `Command` + `B`
## Source Code ## Source code
[packages/extension-bold/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/) [packages/extension-bold/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/)
## Usage ## Usage

4
docs/src/docPages/api/extensions/bullet-list.md
View File

@@ -1,7 +1,7 @@
# BulletList # 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 `* ​`, `- ​` or `+ ​` at the beginning of a new line and it will be magically transformed to a bullet list. Type `* ​`, `- ​` or `+ ​` at the beginning of a new line and it will magically transform to a bullet list.
::: warning Use with ListItem ::: 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. 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.
@@ -20,7 +20,7 @@ The `BulletList` extension is intended to be used with the [`ListItem`](/api/ext
## Keyboard shortcuts ## Keyboard shortcuts
* `Control` + `Shift` + `8` * `Control` + `Shift` + `8`
## Source Code ## Source code
[packages/extension-bullet-list/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/) [packages/extension-bullet-list/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/)
## Usage ## Usage

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

@@ -20,7 +20,7 @@ The CodeBlock extension doesn’t come with styling and has no syntax highlighti
## Keyboard shortcuts ## Keyboard shortcuts
* `Shift` + `Control` + `\` * `Shift` + `Control` + `\`
## Source Code ## Source code
[packages/extension-code-block/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code-block/) [packages/extension-code-block/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code-block/)
## Usage ## Usage

4
docs/src/docPages/api/extensions/code.md
View File

@@ -1,7 +1,7 @@
# Code # Code
The Code extensions enables you to use the `<code>` HTML tag in the editor. If you paste in text with `<code>` tags it will rendered accordingly. The Code extensions enables you to use the `<code>` HTML tag in the editor. If you paste in text with `<code>` tags it will rendered accordingly.
Type something with \`back-ticks around\` and it will be magically transformed to `inline code` while you type. Type something with \`back-ticks around\` and it will magically transform to `inline code` while you type.
## Options ## Options
| Option | Type | Default | Description | | Option | Type | Default | Description |
@@ -16,7 +16,7 @@ Type something with \`back-ticks around\` and it will be magically transformed t
## Keyboard shortcuts ## Keyboard shortcuts
* `Alt` + ` * `Alt` + `
## Source Code ## Source code
[packages/extension-code/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code/) [packages/extension-code/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code/)
## Usage ## Usage

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

@@ -7,7 +7,7 @@ The node is very tiny though. It defines a name of the node (`document`), is con
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.
::: :::
## Source Code ## Source code
[packages/extension-document/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-document/) [packages/extension-document/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-document/)
## Usage ## Usage

2
docs/src/docPages/api/extensions/hard-break.md
View File

@@ -14,7 +14,7 @@ The HardBreak extensions adds support for the `<br>` HTML tag, which forces a li
* Windows & Linux: `Control` + `Enter` * Windows & Linux: `Control` + `Enter`
* macOS: `Command` + `Enter` * macOS: `Command` + `Enter`
## Source Code ## Source code
[packages/extension-hard-break/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-hard-break/) [packages/extension-hard-break/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-hard-break/)
## Usage ## Usage

4
docs/src/docPages/api/extensions/heading.md
View File

@@ -1,7 +1,7 @@
# Heading # Heading
The Heading extension adds support for headings of different levels. Headings are rendered with `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>` or `<h6>` HTML tags. By default all six headline levels are enabled, but you can pass an array to only allow a few levels. Check the usage example to see how this is done. The Heading extension adds support for headings of different levels. Headings are rendered with `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>` or `<h6>` HTML tags. By default all six headline levels are enabled, but you can pass an array to only allow a few levels. Check the usage example to see how this is done.
Type `# ​` at the beginning of a new line and it will be magically transformed to a headline, same for `## ​`, `### ​`, `#### ​`, `##### ​` and `###### ​`. Type `# ​` at the beginning of a new line and it will magically transform to a headline, same for `## ​`, `### ​`, `#### ​`, `##### ​` and `###### ​`.
## Options ## Options
| Option | Type | Default | Description | | Option | Type | Default | Description |
@@ -22,7 +22,7 @@ Type `# ​` at the beginning of a new line and it will be magically transformed
* `Control` + `Shift` + `5` → H5 * `Control` + `Shift` + `5` → H5
* `Control` + `Shift` + `6` → H6 * `Control` + `Shift` + `6` → H6
## Source Code ## Source code
[packages/extension-heading/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-heading/) [packages/extension-heading/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-heading/)
## Usage ## Usage

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

@@ -18,7 +18,7 @@ This extension provides history support. All changes to the document will be tra
* Windows & Linux: `Shift` + `Control` + `Z` * Windows & Linux: `Shift` + `Control` + `Z`
* macOS: `Shift` + `Command` + `Z` * macOS: `Shift` + `Command` + `Z`
## Source Code ## Source code
[packages/extension-history/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-history/) [packages/extension-history/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-history/)
## Usage ## Usage

4
docs/src/docPages/api/extensions/horizontal-rule.md
View File

@@ -1,7 +1,7 @@
# HorizontalRule # HorizontalRule
Use this extension to render a `<hr>` HTML tag. If you pass `<hr>` in the editor’s initial content, it’ll be rendered accordingly. Use this extension to render a `<hr>` HTML tag. If you pass `<hr>` in the editor’s initial content, it’ll be rendered accordingly.
Type three dashes (`---`) or three underscores and a space (`___ ​`) at the beginning of a new line and it will be magically transformed to a horizontal rule. Type three dashes (`---`) or three underscores and a space (`___ ​`) at the beginning of a new line and it will magically transform to a horizontal rule.
## Options ## Options
| Option | Type | Default | Description | | Option | Type | Default | Description |
@@ -16,7 +16,7 @@ Type three dashes (`---`) or three underscores and a space (`___ ​`) at the be
## Keyboard shortcuts ## Keyboard shortcuts
*None* *None*
## Source Code ## Source code
[packages/extension-horizontal-rule/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-horizontal-rule/) [packages/extension-horizontal-rule/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-horizontal-rule/)
## Usage ## Usage

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

@@ -19,7 +19,7 @@ The extension will generate the corresponding `<em>` HTML tags when reading cont
* Windows & Linux: `Control` + `I` * Windows & Linux: `Control` + `I`
* macOS: `Command` + `I` * macOS: `Command` + `I`
## Source Code ## Source code
[packages/extension-italic/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-italic/) [packages/extension-italic/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-italic/)
## Usage ## Usage

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

@@ -12,7 +12,7 @@ Yes, the schema is very strict. Without this extension you won’t even be able
## Keyboard shortcuts ## Keyboard shortcuts
*None* *None*
## Source Code ## Source code
[packages/extension-paragraph/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-paragraph/) [packages/extension-paragraph/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-paragraph/)
## Usage ## Usage

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

@@ -21,7 +21,7 @@ The extension will generate the corresponding `<s>` HTML tags when reading conte
* Windows & Linux: `Control` + `D` * Windows & Linux: `Control` + `D`
* macOS: `Command` + `D` * macOS: `Command` + `D`
## Source Code ## Source code
[packages/extension-strike/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-strike/) [packages/extension-strike/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-strike/)
## Usage ## Usage

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

@@ -5,7 +5,7 @@
Tiptap 1 tried to hide that node from you, but it has always been there. Tiptap 1 tried to hide that node from you, but it has always been there.
::: :::
## Source Code ## Source code
[packages/extension-text/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text/) [packages/extension-text/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-text/)
## Usage ## Usage

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

@@ -19,7 +19,7 @@ The extension will generate the corresponding `<u>` HTML tags when reading conte
* Windows & Linux: `Control` + `U` * Windows & Linux: `Control` + `U`
* macOS: `Command` + `U` * macOS: `Command` + `U`
## Source Code ## Source code
[packages/extension-underline/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-underline/) [packages/extension-underline/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-underline/)
## Usage ## Usage

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

@@ -1 +1,31 @@
# Custom Extensions # Custom Extensions
Let’s extend tiptap with a custom extension!
## 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 `Bold` extension](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/index.ts) and find the default you’d like to change. In that case, the keyboard shortcut.
```js
// 1. Import the extension
import BulletList from '@tiptap/extension-bullet-list'
// 2. Overwrite the keyboard shortcuts
const CustomBulletList = new Node()
.keys(({ editor }) => ({
'Mod-l': () => editor.bulletList(),
}))
.create() // Don’t forget that!
// 3. Add the custom extension to your editor
new Editor({
extensions: [
CustomBulletList(),
// …
]
})
```
## Option 2: Extend existing extensions
## Option 3: Start from scratch

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

@@ -1,19 +1,31 @@
# Custom styling # Custom styling
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: Styling the plain HTML ## Option 1: Style the plain HTML
The content is rendered as HTML, so you can just use that to add styling: 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:
```css ```css
/* Scoped to the editor */
.ProseMirror p {
margin: 1em 0;
}
```
If you’re rendering the stored content somewhere, there won’t be a `.ProseMirror` container, so you can just globally add styling to the used HTML tags:
```css
/* Global styling */
p { p {
margin: 1em 0; margin: 1em 0;
} }
``` ```
## Option 2: Adding custom classes everywhere
Every node has a `class` option, that you can use to add a custom class to the rendered HTML tag. ## 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.
```js ```js
/* Add custom classes */
new Editor({ new Editor({
extensions: [ extensions: [
Document(), Document(),
@@ -28,17 +40,18 @@ new Editor({
}) })
``` ```
This will be the result then: The rendered HTML will look like that:
```html ```html
<h1 class="my-custom-heading">Example Text</p> <h1 class="my-custom-heading">Example Text</p>
<p class="my-custom-paragraph">Wow, that’s really custom.</p> <p class="my-custom-paragraph">Wow, that’s really custom.</p>
``` ```
## Option 3: Customizing the HTML markup ## 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: 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 ```js
/* Customizing the markup */
import Bold from '@tiptap/extension-bold' import Bold from '@tiptap/extension-bold'
const CustomBold = Bold const CustomBold = Bold

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

@@ -27,7 +27,3 @@ If you are using Nuxt.js, note that tiptap needs to run in the client, not on th
::: :::
Congrats! You’ve got it! 🎉 Let’s start to configure your editor in the next step. Congrats! You’ve got it! 🎉 Let’s start to configure your editor in the next step.
### Related links
* [tiptap doesn’t have a default styling](#)

22
docs/src/docPages/guide/get-content.md → docs/src/docPages/guide/store-content.md
View File

@@ -1,16 +1,16 @@
# Get content # Store content
You can store your content as JSON or you can get a good old HTML string. Both work fine. And of course, you can pass both formats to the editor to restore your content. 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.
Funfact: You can store your content as JSON and restore the content from HTML, or the other way around. I don’t know why you would want to do that, but tiptap wouldn’t care. You can store your content as JSON and restore the content from HTML, or the other way around. I don’t know why you would do that, but tiptap wouldn’t care.
## Option 1: Work with JSON ## Option 1: JSON
JSON is probably easier to loop through, for example to look for a mention and it’s more like what tiptap uses under the hood. Anyway, if you want to use JSON to store the content we provide a method to retrieve JSON: JSON is probably easier to loop through, for example to look for a mention and it’s more like what tiptap uses under the hood. Anyway, if you want to use JSON to store the content we provide a method to retrieve the content as JSON:
```js ```js
const json = editor.json() const json = editor.json()
``` ```
You can store that in your database or send it to an API and restore the document initially like that: You can store that in your database (or send it to an API) and restore the document initially like that:
```js ```js
new Editor({ new Editor({
@@ -51,7 +51,7 @@ editor.setContent({
}) })
``` ```
## Option 2: Work with HTML ## Option 2: HTML
HTML can be easily rendered in other places, for example in emails and it’s wildly used, so it’s probably easier to switch the editor at some point. Anyway, every editor instance provides a method to get HTML from the current document: HTML can be easily rendered in other places, for example in emails and it’s wildly used, so it’s probably easier to switch the editor at some point. Anyway, every editor instance provides a method to get HTML from the current document:
```js ```js
@@ -74,9 +74,13 @@ editor.setContent(`<p>Example Text</p>`)
## Not an option: Markdown ## Not an option: Markdown
Unfortunately, tiptap doesn’t support Markdown as input/output format. We considered to add support for it, but there are a few limitations: Unfortunately, **tiptap doesn’t support Markdown as an input or output format**. We considered to add support for it, but there are a few limitations:
* HTML and JSON can both have deeply nested structures, Markdown can’t have those * HTML and JSON can both have deeply nested structures, Markdown can’t have those
* Tables are not part of the Markdown standard, and can’t easily be stored and restored from Markdown * Tables are not part of the Markdown standard, and can’t easily be stored and restored from Markdown
You should really consider to work with HTML or JSON to store your content. 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. 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.
That said, tiptap **does** support Markdown shortcuts to format your content. Try typing `**two asterisk**` to make your text bold for example.

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

@@ -1,16 +1,25 @@
:::warning Don’t try this at home
This version of tiptap is not production-ready, don’t use it anywhere.
:::
# Introduction # Introduction
tiptap is a renderless wrapper around [ProseMirror](https://ProseMirror.net) – a toolkit for building rich-text editors that are 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 is built on top of its APIs and we strongly recommend you to read through the [ProseMirror Guide](https://ProseMirror.net/docs/guide/). You’ll have a better understanding of how everything works under the hood and get familiar with many terms and jargon used by tiptap. [![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)
[![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis)
## Renderless 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*.
The implementation of a text editor can be very specific for each use case. We don’t want to 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’ll have full control over markup and styling.
## TypeScript 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.
Tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE supports those), helps us to find bugs early and makes it possible to generate [a complete API documentation](#) on top of the extensive human written documentation.
## Framework-agnostic ## Features
We don’t care what framework you use. Tiptap is ready to be used with plain JavaScript, Vue.js or React. That makes it even possible to write a renderer for Svelte and others.
**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, Vue.js or React. That makes it even possible to write a renderer for Svelte and others.
**TypeScript.** Tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE for it), 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? ## Who uses tiptap?
- [GitLab](https://gitlab.com) - [GitLab](https://gitlab.com)
@@ -19,5 +28,4 @@ We don’t care what framework you use. Tiptap is ready to be used with plain Ja
- [ApostropheCMS](https://apostrophecms.com) - [ApostropheCMS](https://apostrophecms.com)
- [Directus CMS](https://directus.io) - [Directus CMS](https://directus.io)
- [Nextcloud](https://apps.nextcloud.com/apps/text) - [Nextcloud](https://apps.nextcloud.com/apps/text)
- [Craft CMS](https://craftcms.com/)
- [and many more →](https://github.com/ueberdosis/tiptap/network/dependents?package_id=UGFja2FnZS0xMzE5OTg0ODc%3D) - [and many more →](https://github.com/ueberdosis/tiptap/network/dependents?package_id=UGFja2FnZS0xMzE5OTg0ODc%3D)

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

@@ -1,8 +1,8 @@
# Contributing # Contributing
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 contributions: 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:
## What kind of contributions are welcome ## Examples
* Improved documentation, e. g. fixing typos, new sections, further explanation …) * Improved documentation, e. g. fixing typos, new sections, further explanation …)
* New features for existing extensions, e. g. a new option * New features for existing extensions, e. g. a new option

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

@@ -1,10 +1,16 @@
# Installation # Installation
tiptap has a very modular package structure and is independent of any framework. Depending on what you want to do with tiptap there are a few different ways to install tiptap in your project. Choose the way that fits your project best. 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.
## Plain JavaScript ## Overview <!-- omit in toc -->
Use tiptap with vanilla JavaScript for a very lightweight and raw experience. If you feel like it, you can even use it to connect the tiptap core with other frameworks not mentioned here. - [Option 1: Vanilla JavaScript](#option-1-vanilla-javascript)
- [Option 2: Vue.js](#option-2-vuejs)
- [Option 3: CodeSandbox](#option-3-codesandbox)
## Option 1: Vanilla JavaScript
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 ```bash
# With npm # With npm
@@ -14,6 +20,11 @@ npm install @tiptap/core @tiptap/starter-kit
yarn add @tiptap/core @tiptap/starter-kit yarn add @tiptap/core @tiptap/starter-kit
``` ```
| Package | Description |
| ---------------------------------------------------------------------------- | -------------------------- |
| [@tiptap/core](https://www.npmjs.com/package/@tiptap/core) | The actual editor |
| [@tiptap/starter-kit](https://www.npmjs.com/package/@tiptap/vue-starter-kit) | The most common extensions |
Great, that should be enough to start. Here is the most essential code you need to get a running instance of tiptap: Great, that should be enough to start. Here is the most essential code you need to get a running instance of tiptap:
```js ```js
@@ -27,26 +38,32 @@ new Editor({
}) })
``` ```
## Vue.js ## Option 2: Vue.js
To use tiptap with Vue.js (and tools that are based on Vue.js) install the Vue.js adapter in your project: To use tiptap with Vue.js (and tools that are based on Vue.js) install tiptap together with the Vue.js rendering adapter in your project. We even prepared a Vue.js starter kit, which gives you a good headstart.
```bash ```bash
# With npm # With npm
npm install @tiptap/vue @tiptap/vue-starter-kit npm install @tiptap/core @tiptap/vue @tiptap/vue-starter-kit
# Or: With Yarn # Or: With Yarn
yarn add @tiptap/vue @tiptap/vue-starter-kit yarn add @tiptap/core @tiptap/vue @tiptap/vue-starter-kit
``` ```
We even prepared a Vue.js starter kit for you. That should give you a good headstart. Create a new component and add the following content to get a basic version of tiptap: | Package | Description |
| -------------------------------------------------------------------------------- | --------------------------------------------- |
| [@tiptap/core](https://www.npmjs.com/package/@tiptap/core) | The actual editor |
| [@tiptap/vue](https://www.npmjs.com/package/@tiptap/vue) | Rendering for Vue.js |
| [@tiptap/vue-starter-kit](https://www.npmjs.com/package/@tiptap/vue-starter-kit) | The most common extensions wrapped for Vue.js |
Create a new component and add the following content to get a basic version of tiptap:
<demo name="General/Installation" /> <demo name="General/Installation" />
## CodeSandbox ## Option 3: CodeSandbox
CodeSandbox is an online coding environment. It’s great to fiddle around without setting up a local project and it’s great to share your code with others. CodeSandbox is an online coding environment. It’s great to fiddle around without setting up a local project and to share your code with others.
It’s also amazing for bug reports. Try to recreate a bug there and share it with us before you [file an issue on GitHub](https://github.com/ueberdosis/tiptap-next/issues/new). This helps a ton to fix bugs faster. It’s also amazing for bug reports. Found it a bug? Try to recreate it there and share it with us before you [file an issue on GitHub](https://github.com/ueberdosis/tiptap-next/issues/new). That helps to fix bugs faster.
* [Vue.js/tiptap on CodeSandbox](https://codesandbox.io/s/vue-issue-template-h0g28) * [Vue.js/tiptap on CodeSandbox](https://codesandbox.io/s/vue-issue-template-h0g28)

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

@@ -1,19 +1,20 @@
# Upgrade Guide # Upgrade Guide
## Reasons to upgrade to tiptap 2.x ## Reasons to upgrade to tiptap 2.x
* autocomplete in your IDE (thanks to TypeScript) 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
* an amazing documentation with 100+ pages
* active development, new features in the making * Autocomplete in your IDE (thanks to TypeScript)
* tons of new extensions planned * Amazing documentation with 100+ pages
* well-tested code base * Active development, new features in the making
* Tons of new extensions planned
* Well-tested code base
## Upgrading from 1.x to 2.x ## 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: 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:
### 1. Explicitly register the Document, Text and Paragraph extensions ### 1. Explicitly register the Document, Text and Paragraph extensions
Tiptap 1 tried to hide a few required extensions from you. Be sure to explicitly import 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/extensions/document), [Paragraph](/api/extensions/paragraph) and [Text](/api/extensions/text) extensions.
```js ```js
import Document from '@tiptap/extension-document' import Document from '@tiptap/extension-document'
@@ -25,16 +26,19 @@ new Editor({
Document(), Document(),
Paragraph(), Paragraph(),
Text(), Text(),
… // all your other extensions
] ]
}) })
``` ```
### 2. New document type ### 2. 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. **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 ```js
import Document from '@tiptap/extension-document' import Document from '@tiptap/extension-document'
const CustomDocument = Document.name('doc').create() const CustomDocument = Document.name('doc').create()
new Editor({ new Editor({
@@ -46,13 +50,36 @@ new Editor({
``` ```
### 3. New extension API ### 3. 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.
In case you’ve built some custom extensions for your project, you’ll need to rewrite them to fit the new API. No worries, though, you can keep a lot of your work though. The schema, commands, keys, inputRules, pasteRules all work like they did before. It’s just different how you register them.
```js ```js
const CustomExtension = … import { Node } from '@tiptap/core'
const CustomExtension = new Node()
.name('custom_extension')
.defaults({
// …
})
.schema(() => ({
// …
}))
.commands(({ editor, name }) => ({
// …
}))
.keys(({ editor }) => ({
// …
}))
.inputRules(({ type }) => [
// …
])
.pasteRules(({ type }) => [
// …
])
.create()
``` ```
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.
### 4. Blockquotes must not be nested anymore ### 4. Blockquotes must not be nested anymore
:::warning Breaking Change :::warning Breaking Change

11
docs/src/layouts/App/index.vue
View File

@@ -107,15 +107,10 @@ export default {
return this.$route.matched[0].path return this.$route.matched[0].path
}, },
editLink () { editLink () {
let path = this.currentPath const currentPath = this.currentPath
const filePath = currentPath === '' ? '/introduction' : currentPath
if (path === '') { return `https://github.com/ueberdosis/tiptap-next/blob/main/docs/src/docPages${filePath}.md`
path = 'docs/src/pages/Index.vue'
} else {
path = `docs/src/docPages${path}.md`
}
return `https://github.com/ueberdosis/tiptap-next/blob/main/${path}`
}, },
}, },

5
docs/src/links.yaml
View File

@@ -20,8 +20,8 @@
draft: true draft: true
- title: Custom styling - title: Custom styling
link: /guide/custom-styling link: /guide/custom-styling
- title: Get content - title: Store content
link: /guide/get-content link: /guide/store-content
- title: Custom extensions - title: Custom extensions
link: /guide/custom-extensions link: /guide/custom-extensions
draft: true draft: true
@@ -98,7 +98,6 @@
items: items:
- title: Editor - title: Editor
link: /api/editor/ link: /api/editor/
draft: true
- title: Extensions - title: Extensions
link: /api/extensions/ link: /api/extensions/
items: items: