Merge branch 'main' of https://github.com/ueberdosis/tiptap-next into feature/improve-command-chaining
This commit is contained in:
Philipp Kühn
11
README.md
11
README.md
@@ -10,6 +10,17 @@ A renderless and extendable rich-text editor for [Vue.js](https://github.com/vue
|
||||
[](https://github.com/ueberdosis/tiptap-next/actions)
|
||||
[](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
|
||||
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*.
|
||||
|
||||
|
||||
@@ -36,7 +36,9 @@ export default {
|
||||
CodeBlock(),
|
||||
],
|
||||
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++)
|
||||
{
|
||||
if (i % 15 == 0)
|
||||
@@ -48,7 +50,9 @@ export default {
|
||||
else
|
||||
console.log(i);
|
||||
}</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>
|
||||
`,
|
||||
})
|
||||
},
|
||||
|
||||
@@ -57,7 +57,7 @@ export default () => {
|
||||
<button onClick={() => alert(JSON.stringify(value))}>Alert state</button>
|
||||
</p>
|
||||
<hr style={{ margin: '0.85rem 0'}} />
|
||||
<Editor
|
||||
<Editor
|
||||
value={value}
|
||||
onChange={setValue}
|
||||
extensions={extensions()}
|
||||
|
||||
@@ -1,25 +1,28 @@
|
||||
# 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.
|
||||
|
||||
## Editor Properties
|
||||
| Property | Type | Default | Description |
|
||||
| ---------------------- | :--------------: | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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. |
|
||||
| `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. |
|
||||
| `extensions` | `Array` | `[]` | A list of extensions used, by the editor. This can be `Nodes`, `Marks` or `Plugins`. |
|
||||
| `useBuiltInExtensions` | `Boolean` | `true` | By default tiptap adds a `Doc`, `Paragraph` and `Text` node to the Prosemirror schema. |
|
||||
| `dropCursor` | `Object` | `{}` | Config for `prosemirror-dropcursor`. |
|
||||
| `enableDropCursor` | `Boolean` | `true` | Option to enable / disable the dropCursor 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). |
|
||||
| `onInit` | `Function` | `undefined` | This will return an Object with the current `state` and `view` of Prosemirror on init. |
|
||||
| `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. |
|
||||
| `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. |
|
||||
## Settings
|
||||
All of the listed settings can be set during initialization, read and updated during runtime.
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
| ------------------ | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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` | Option to enable / disable the dropCursor plugin. |
|
||||
| `enableGapCursor` | `Boolean` | `true` | Option to enable / disable the gapCursor plugin. |
|
||||
| `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). |
|
||||
|
||||
## Hooks
|
||||
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. |
|
||||
|
||||
@@ -11,9 +11,9 @@ const editor = new Editor({
|
||||
onInit: () => {
|
||||
// editor is initialized
|
||||
},
|
||||
onUpdate: ({ getHTML }) => {
|
||||
onUpdate: ({ html }) => {
|
||||
// get new content on update
|
||||
const newContent = getHTML()
|
||||
const newContent = html()
|
||||
},
|
||||
})
|
||||
```
|
||||
@@ -27,8 +27,8 @@ editor.on('init', () => {
|
||||
// editor is initialized
|
||||
})
|
||||
|
||||
editor.on('update', ({ getHTML }) => {
|
||||
editor.on('update', ({ html }) => {
|
||||
// get new content on update
|
||||
const newContent = getHTML()
|
||||
const newContent = html()
|
||||
})
|
||||
```
|
||||
|
||||
@@ -1,7 +1,16 @@
|
||||
# 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.
|
||||
|
||||
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
|
||||
| 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`
|
||||
* macOS: `Command` + `Shift` + `9`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-blockquote/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-blockquote/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 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.
|
||||
|
||||
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
|
||||
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`
|
||||
* macOS: `Command` + `B`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-bold/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bold/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# BulletList
|
||||
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
|
||||
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
|
||||
* `Control` + `Shift` + `8`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-bullet-list/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-bullet-list/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -20,7 +20,7 @@ The CodeBlock extension doesn’t come with styling and has no syntax highlighti
|
||||
## Keyboard shortcuts
|
||||
* `Shift` + `Control` + `\`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-code-block/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code-block/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 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.
|
||||
|
||||
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
|
||||
| Option | Type | Default | Description |
|
||||
@@ -16,7 +16,7 @@ Type something with \`back-ticks around\` and it will be magically transformed t
|
||||
## Keyboard shortcuts
|
||||
* `Alt` + `
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-code/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-code/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -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.
|
||||
:::
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-document/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-document/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -14,7 +14,7 @@ The HardBreak extensions adds support for the `<br>` HTML tag, which forces a li
|
||||
* Windows & Linux: `Control` + `Enter`
|
||||
* macOS: `Command` + `Enter`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-hard-break/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-hard-break/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 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.
|
||||
|
||||
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
|
||||
| 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` + `6` → H6
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-heading/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-heading/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -18,7 +18,7 @@ This extension provides history support. All changes to the document will be tra
|
||||
* Windows & Linux: `Shift` + `Control` + `Z`
|
||||
* macOS: `Shift` + `Command` + `Z`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-history/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-history/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 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.
|
||||
|
||||
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
|
||||
| Option | Type | Default | Description |
|
||||
@@ -16,7 +16,7 @@ Type three dashes (`---`) or three underscores and a space (`___ `) at the be
|
||||
## Keyboard shortcuts
|
||||
*None*
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-horizontal-rule/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-horizontal-rule/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -19,7 +19,7 @@ The extension will generate the corresponding `<em>` HTML tags when reading cont
|
||||
* Windows & Linux: `Control` + `I`
|
||||
* macOS: `Command` + `I`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-italic/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-italic/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -12,7 +12,7 @@ Yes, the schema is very strict. Without this extension you won’t even be able
|
||||
## Keyboard shortcuts
|
||||
*None*
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-paragraph/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-paragraph/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -21,7 +21,7 @@ The extension will generate the corresponding `<s>` HTML tags when reading conte
|
||||
* Windows & Linux: `Control` + `D`
|
||||
* macOS: `Command` + `D`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-strike/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-strike/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
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/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -19,7 +19,7 @@ The extension will generate the corresponding `<u>` HTML tags when reading conte
|
||||
* Windows & Linux: `Control` + `U`
|
||||
* macOS: `Command` + `U`
|
||||
|
||||
## Source Code
|
||||
## Source code
|
||||
[packages/extension-underline/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-underline/)
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -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
|
||||
@@ -1,19 +1,31 @@
|
||||
# Custom styling
|
||||
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
|
||||
The content is rendered as HTML, so you can just use that to add styling:
|
||||
## 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:
|
||||
|
||||
```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 {
|
||||
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
|
||||
/* Add custom classes */
|
||||
new Editor({
|
||||
extensions: [
|
||||
Document(),
|
||||
@@ -28,17 +40,18 @@ new Editor({
|
||||
})
|
||||
```
|
||||
|
||||
This will be the result then:
|
||||
The rendered HTML will look like that:
|
||||
|
||||
```html
|
||||
<h1 class="my-custom-heading">Example Text</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:
|
||||
|
||||
```js
|
||||
/* Customizing the markup */
|
||||
import Bold from '@tiptap/extension-bold'
|
||||
|
||||
const CustomBold = Bold
|
||||
|
||||
@@ -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.
|
||||
|
||||
### Related links
|
||||
|
||||
* [tiptap doesn’t have a default styling](#)
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
# Get 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.
|
||||
# Store 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
|
||||
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:
|
||||
## 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 the content as JSON:
|
||||
|
||||
```js
|
||||
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
|
||||
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:
|
||||
|
||||
```js
|
||||
@@ -74,9 +74,13 @@ editor.setContent(`<p>Example Text</p>`)
|
||||
|
||||
## 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
|
||||
* 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.
|
||||
@@ -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
|
||||
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.
|
||||
[](https://www.npmjs.com/package/@tiptap/core)
|
||||
[](https://npmcharts.com/compare/@tiptap/core?minimal=true)
|
||||
[](https://www.npmjs.com/package/@tiptap/core)
|
||||
[](https://github.com/sponsors/ueberdosis)
|
||||
|
||||
## Renderless
|
||||
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.
|
||||
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*.
|
||||
|
||||
## TypeScript
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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.
|
||||
## Features
|
||||
|
||||
**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?
|
||||
- [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)
|
||||
- [Directus CMS](https://directus.io)
|
||||
- [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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -107,15 +107,10 @@ export default {
|
||||
return this.$route.matched[0].path
|
||||
},
|
||||
editLink () {
|
||||
let path = this.currentPath
|
||||
const currentPath = this.currentPath
|
||||
const filePath = currentPath === '' ? '/introduction' : currentPath
|
||||
|
||||
if (path === '') {
|
||||
path = 'docs/src/pages/Index.vue'
|
||||
} else {
|
||||
path = `docs/src/docPages${path}.md`
|
||||
}
|
||||
|
||||
return `https://github.com/ueberdosis/tiptap-next/blob/main/${path}`
|
||||
return `https://github.com/ueberdosis/tiptap-next/blob/main/docs/src/docPages${filePath}.md`
|
||||
},
|
||||
},
|
||||
|
||||
|
||||
@@ -20,8 +20,8 @@
|
||||
draft: true
|
||||
- title: Custom styling
|
||||
link: /guide/custom-styling
|
||||
- title: Get content
|
||||
link: /guide/get-content
|
||||
- title: Store content
|
||||
link: /guide/store-content
|
||||
- title: Custom extensions
|
||||
link: /guide/custom-extensions
|
||||
draft: true
|
||||
@@ -98,7 +98,6 @@
|
||||
items:
|
||||
- title: Editor
|
||||
link: /api/editor/
|
||||
draft: true
|
||||
- title: Extensions
|
||||
link: /api/extensions/
|
||||
items:
|
||||
|
||||
Reference in New Issue
Block a user