Merge branch 'main' of https://github.com/ueberdosis/tiptap-next into feature/improve-command-chaining
This commit is contained in:
Philipp Kühn
@@ -1,8 +1,8 @@
|
||||
# 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 …)
|
||||
* New features for existing extensions, e. g. a new option
|
||||
|
||||
@@ -1,10 +1,16 @@
|
||||
# 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
|
||||
# With npm
|
||||
@@ -14,6 +20,11 @@ npm install @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:
|
||||
|
||||
```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
|
||||
# With npm
|
||||
npm install @tiptap/vue @tiptap/vue-starter-kit
|
||||
npm install @tiptap/core @tiptap/vue @tiptap/vue-starter-kit
|
||||
|
||||
# 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" />
|
||||
|
||||
## 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)
|
||||
|
||||
@@ -1,19 +1,20 @@
|
||||
# Upgrade Guide
|
||||
|
||||
## Reasons to upgrade to tiptap 2.x
|
||||
* autocomplete in your IDE (thanks to TypeScript)
|
||||
* an amazing documentation with 100+ pages
|
||||
* active development, new features in the making
|
||||
* tons of new extensions planned
|
||||
* well-tested code base
|
||||
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)
|
||||
* Amazing documentation with 100+ pages
|
||||
* Active development, new features in the making
|
||||
* Tons of new extensions planned
|
||||
* Well-tested code base
|
||||
|
||||
## 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:
|
||||
|
||||
### 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
|
||||
import Document from '@tiptap/extension-document'
|
||||
@@ -25,16 +26,19 @@ new Editor({
|
||||
Document(),
|
||||
Paragraph(),
|
||||
Text(),
|
||||
…
|
||||
// all your other extensions
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
```js
|
||||
import Document from '@tiptap/extension-document'
|
||||
|
||||
const CustomDocument = Document.name('doc').create()
|
||||
|
||||
new Editor({
|
||||
@@ -46,13 +50,36 @@ new Editor({
|
||||
```
|
||||
|
||||
### 3. New extension API
|
||||
|
||||
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.
|
||||
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
|
||||
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
|
||||
|
||||
:::warning Breaking Change
|
||||
|
||||
Reference in New Issue
Block a user