docs: remove most of the tables from the content (to improve the searchability)

This commit is contained in:
Hans Pagel
2021-10-07 21:02:30 +02:00
parent 9ed883edd4
commit c5f025909e
8 changed files with 183 additions and 104 deletions

View File

@@ -4,7 +4,7 @@ tableOfContents: true
# Upgrade Guide
## Reasons to upgrade to tiptap v2
## Introduction
First of all, tiptap v1 isnt supported anymore and wont receive any further updates.
Yes, its tedious work to upgrade your favorite text editor to a new API, but we made sure youve got enough reasons to upgrade to the newest version.
@@ -15,10 +15,9 @@ Yes, its tedious work to upgrade your favorite text editor to a new API, but
* Tons of new extensions
* Well-tested code base
## Upgrading from v1 to v2
The new API will look pretty familiar to you, but there are a ton of changes though. To make the upgrade a little bit easier, here is everything you need to know:
### Uninstall tiptap v1
## Uninstall tiptap v1
The whole package structure has changed, we even moved to another npm namespace, so youll need to remove the old version entirely before upgrading to tiptap 2.
Otherwise youll run into an exception, for example “looks like multiple versions of prosemirror-model were loaded”.
@@ -31,7 +30,7 @@ npm uninstall tiptap tiptap-commands tiptap-extensions tiptap-utils
yarn remove tiptap tiptap-commands tiptap-extensions tiptap-utils
```
### Install tiptap v2
## Install tiptap v2
Once you have uninstalled the old version of tiptap, install the new Vue 2 package and the starter kit:
@@ -43,7 +42,7 @@ npm install @tiptap/vue-2 @tiptap/starter-kit
yarn add @tiptap/vue-2 @tiptap/starter-kit
```
### Keep tiptap v2 up to date
## Keep tiptap v2 up to date
We are constantly releasing updates to tiptap. Did you know theres an easy-to-use command to update your dependencies with Yarn?
```bash
@@ -56,7 +55,7 @@ You can add the `--latest` flag, to show all possible upgrades even if they
yarn upgrade-interactive --latest
```
### Explicitly register the Document, Text and Paragraph extensions
## 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 youre 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
@@ -76,7 +75,7 @@ new Editor({
And we removed some settings: `dropCursor`, `enableDropCursor`, and `enableGapCursor`. Those are separate extensions now: [`Dropcursor`](/api/extensions/dropcursor) and [`Gapcursor`](/api/extensions/gapcursor). You probably want to load them, but if you dont, just ignore this.
### New names for most extensions
## New names for most extensions
We switched to lowerCamelCase, so theres a lot type names that changed. If you stored your content as JSON you need to loop through it and rename them. Sorry for that one.
| Old type | New type |
@@ -93,10 +92,10 @@ We switched to lowerCamelCase, so theres a lot type names that changed. If yo
| ~~`todo_list`~~ | `taskList` (new name!) |
| ~~`todo_item`~~ | `taskItem` (new name!) |
### Removed methods
## Removed methods
We removed the `.state()` method. No worries though, its still available through `editor.state`.
### New extension API
## New extension API
In case youve built some custom extensions for your project, youre 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. Its just different how you register them.
```js
@@ -131,14 +130,14 @@ const CustomExtension = Node.create({
Read more about [all the nifty details building custom extensions](/guide/custom-extensions) in our guide.
### Renamed settings and methods
## Renamed settings and methods
[We renamed a lot of settings and methods](/api/editor). Hopefully you can migrate to the new API with search & replace. Here is a list of what changed:
| Old name | New name |
| --------------- | ----------- |
| ~~`autoFocus`~~ | `autofocus` |
### Renamed commands
## Renamed commands
All new extensions come with specific commands to set, unset and toggle styles. So instead of `.bold()`, its now `.toggleBold()`. Also, we switched to lowerCamelCase, below are a few examples. Oh, and we renamed `todo_list`, to `taskList`, sorry for that one.
| Old command | New command |
@@ -162,10 +161,10 @@ All new extensions come with specific commands to set, unset and toggle styles.
| ~~`.underline()`~~ | `.toggleUnderline()` |
| … | … |
### MenuBar, BubbleMenu and FloatingMenu
## MenuBar, BubbleMenu and FloatingMenu
Read the dedicated [guide on creating menus](/guide/menus) to migrate your menus.
### Commands can be chained now
## Commands can be chained now
Most commands can be combined to one call now. Thats shorter than separate function calls in most cases. Here is an example to make the selected text bold:
```js
@@ -174,7 +173,7 @@ editor.chain().toggleBold().focus().run()
The `.chain()` is required to start a new chain and the `.run()` is needed to actually execute all the commands in between. Read more about [the new tiptap commands](/api/commands) in our API documentation.
### .focus() isnt called on every command anymore
## .focus() isnt called on every command anymore
We tried to hide the `.focus()` command from you with tiptap 1 and executed that on every command. That led to issues in specific use cases, where you want to run a command, but dont want to focus the editor.
With tiptap v2 you have to explicitly call the `focus()` and you probably want to do that in a lot of places. Here is an example:
@@ -183,18 +182,18 @@ With tiptap v2 you have to explicitly call the `focus()` and you probably want t
editor.chain().focus().toggleBold().run()
```
### Event callbacks have fewer parameters
## Event callbacks have fewer parameters
The new event callbacks have fewer parameters. The same things should be available through `this.` now. [Read more about events here.](/api/events)
### Collaborative editing
## Collaborative editing
The reference implementation for collaborative editing uses Y.js now. Thats a whole different thing. You still can use the tiptap 1 extension, but its up to you to adapt it to the new extension API. If youve done this, dont forget to share it with us so we can link to it from here!
Read more about [the new collaborative editing experience](/guide/collaborative-editing) in our guide.
### Marks dont support node view anymore
## Marks dont support node view anymore
For marks, node views are [not well supported in ProseMirror](https://discuss.prosemirror.net/t/there-is-a-bug-in-marks-nodeview/2722/2). There is also [a related issue](https://github.com/ueberdosis/tiptap/issues/613) for tiptap 1. Thats why we removed it in tiptap 2.
### Become a sponsor
## Become a sponsor
tiptap wouldnt exist without the funding of its community. If you fell in love with tiptap, dont forget to [become a sponsor](/sponsor) and make the maintenance, development and support sustainable.
In exchange, well take you into our hearts, invite you to private repositories, add a `sponsor ♥` label to your issues and pull requests and more.