Merge branch 'main' into feature/generate-html-from-json-document

# Conflicts:
#	packages/core/src/ExtensionManager.ts
This commit is contained in:
Philipp Kühn
2020-09-09 20:50:53 +02:00
59 changed files with 929 additions and 785 deletions

View File

@@ -9,12 +9,7 @@ import { Editor, EditorContent } from '@tiptap/vue-starter-kit'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
import History from '@tiptap/extension-history'
import Bold from '@tiptap/extension-bold'
import Italic from '@tiptap/extension-italic'
import Code from '@tiptap/extension-code'
import CodeBlock from '@tiptap/extension-codeblock'
import Heading from '@tiptap/extension-heading'
import Focus from '@tiptap/extension-focus'
export default {
@@ -31,16 +26,11 @@ export default {
mounted() {
this.editor = new Editor({
extensions: [
new Document(),
new History(),
new Paragraph(),
new Text(),
new Bold(),
new Italic(),
new Code(),
new CodeBlock(),
new Heading(),
new Focus({
Document(),
Paragraph(),
Text(),
Code(),
Focus({
className: 'has-focus',
nested: true,
}),
@@ -48,16 +38,12 @@ export default {
autoFocus: true,
content: `
<p>
With the focus extension you can add custom classes to focused nodes. Default options:
The focus extension adds custom classes to focused nodes. By default, itll add a <code>has-focus</code> class, even to nested nodes:
</p>
<pre><code>{\n className: 'has-focus',\n nested: true,\n}</code></pre>
<pre><code>{ className: 'has-focus', nested: true }</code></pre>
<ul>
<li>
When set <code>nested</code> to <code>true</code> also nested elements like this list item will be captured.
</li>
<li>
Otherwise only the wrapping list will get this class.
</li>
<li>With <code>nested: true</code> nested elements like this list item will be focused.</li>
<li>Otherwise the whole list will get the focus class, even if only a single list item is selected.</li>
</ul>
`,
})

View File

@@ -24,9 +24,9 @@ export default {
this.editor = new Editor({
content: '<p>This is a radically reduced version of tiptap for minimalisits. It has only support for a document, paragraphs and text, thats it.</p>',
extensions: [
new Document(),
new Paragraph(),
new Text(),
Document(),
Paragraph(),
Text(),
],
})

View File

@@ -26,10 +26,10 @@ export default {
this.editor = new Editor({
content: '<p>Im running tiptap with Vue.js. This demo is interactive, try to edit the text.</p>',
extensions: [
new Document(),
new Paragraph(),
new Text(),
new Bold(),
Document(),
Paragraph(),
Text(),
Bold(),
],
})
},

View File

@@ -30,10 +30,10 @@ export default {
mounted() {
this.editor = new Editor({
extensions: [
new Document(),
new Paragraph(),
new Text(),
new Bold(),
Document(),
Paragraph(),
Text(),
Bold(),
],
content: `
<p>This isnt bold.</p>

View File

@@ -30,10 +30,10 @@ export default {
mounted() {
this.editor = new Editor({
extensions: [
new Document(),
new Paragraph(),
new Text(),
new Code(),
Document(),
Paragraph(),
Text(),
Code(),
],
content: `
<p>This isnt code.</p>

View File

@@ -0,0 +1,5 @@
context('/api/extensions/document', () => {
beforeEach(() => {
cy.visit('/api/extensions/document')
})
})

View File

@@ -0,0 +1,44 @@
<template>
<div v-if="editor">
<editor-content :editor="editor" />
</div>
</template>
<script>
import { Editor } from '@tiptap/core'
import { EditorContent } from '@tiptap/vue'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
export default {
components: {
EditorContent,
},
data() {
return {
editor: null,
}
},
mounted() {
this.editor = new Editor({
extensions: [
Document(),
Paragraph(),
Text(),
],
content: `
<p>The Document extension is required. Though, you can write your own implementation, e. g. to give it custom name.</p>
`,
})
window.editor = this.editor
},
beforeDestroy() {
this.editor.destroy()
}
}
</script>

View File

@@ -33,10 +33,10 @@ export default {
mounted() {
this.editor = new Editor({
extensions: [
new Document(),
new Paragraph(),
new Text(),
new History(),
Document(),
Paragraph(),
Text(),
History(),
],
content: `
<p>Edit this text and press undo to test this extension.</p>

View File

@@ -30,10 +30,10 @@ export default {
mounted() {
this.editor = new Editor({
extensions: [
new Document(),
new Paragraph(),
new Text(),
new Italic(),
Document(),
Paragraph(),
Text(),
Italic(),
],
content: `
<p>This isnt italic.</p>

View File

@@ -0,0 +1,5 @@
context('/api/extensions/paragraph', () => {
beforeEach(() => {
cy.visit('/api/extensions/paragraph')
})
})

View File

@@ -0,0 +1,44 @@
<template>
<div v-if="editor">
<editor-content :editor="editor" />
</div>
</template>
<script>
import { Editor } from '@tiptap/core'
import { EditorContent } from '@tiptap/vue'
import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
export default {
components: {
EditorContent,
},
data() {
return {
editor: null,
}
},
mounted() {
this.editor = new Editor({
extensions: [
Document(),
Paragraph(),
Text(),
],
content: `
<p>The Paragraph extension is not required, but its very likely you want to use it. Its needed to write paragraphs of text. 🤓</p>
`,
})
window.editor = this.editor
},
beforeDestroy() {
this.editor.destroy()
}
}
</script>

View File

@@ -55,15 +55,15 @@ export default {
this.editor = new Editor({
content: '<h2>Hey there!</h2><p>This editor is based on Prosemirror, fully extendable and renderless. You can easily add custom nodes as Vue components.</p>',
extensions: [
new Document(),
new Paragraph(),
new Text(),
new CodeBlock(),
new History(),
new Bold(),
new Italic(),
new Code(),
new Heading(),
Document(),
Paragraph(),
Text(),
CodeBlock(),
History(),
Bold(),
Italic(),
Code(),
Heading(),
],
})
},

View File

@@ -1 +1,34 @@
# Events
# Events
:::warning Out of date
This content is written for tiptap 1 and needs an update.
:::
There are some events you can listen for. A full list of events can be found [here](/api/classes.md#editor-options).
```js
const editor = new Editor({
onInit: () => {
// editor is initialized
},
onUpdate: ({ getHTML }) => {
// get new content on update
const newContent = getHTML()
},
})
```
It's also possible to register event listeners afterwards.
```js
const editor = new Editor()
editor.on('init', () => {
// editor is initialized
})
editor.on('update', ({ getHTML }) => {
// get new content on update
const newContent = getHTML()
})
```

View File

@@ -2,7 +2,9 @@
The Blockquote extension enables you to use the `<blockquote>` HTML tag in the editor.
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
@@ -39,7 +41,7 @@ export default {
return {
editor: new Editor({
extensions: [
new Blockquote(),
Blockquote(),
],
content: `
<blockquote>

View File

@@ -6,7 +6,9 @@ The extension will generate the corresponding `<strong>` HTML tags when reading
:::
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |

View File

@@ -6,7 +6,9 @@ Its intended to be used with the `ListItem` extension.
:::
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
@@ -43,7 +45,7 @@ export default {
return {
editor: new Editor({
extensions: [
new BulletList(),
BulletList(),
],
content: `
<ul>

View File

@@ -2,7 +2,9 @@
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.
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |

View File

@@ -1 +1,14 @@
# Document
# Document
**The `Document` extension is required**, no matter what you build with tiptap. Its a so called “topNode”, a node thats the home to all other nodes. Think of it like the `<body>` tag for your document.
The node is very tiny though. It defines a name of the node (`document`), is configured to be a top node (`topNode: true`) and that it can contain multiple other nodes (`block`). Thats all. But have a look yourself:
:::warning Breaking Change from 1.x → 2.x
Tiptap 1 tried to hide that node from you, but it has always been there. A tiny, but important change though: **We renamed the default type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name.
:::
## Source Code
[packages/extension-document/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-document/)
## Usage
<demo name="Extensions/Document" highlight="10,28" />

View File

@@ -3,7 +3,8 @@ Enables you to use headline HTML tags in the editor.
## Options
| Option | Type | Default | Description |
| ------ | ---- | ---- | ----- |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
| levels | Array | [1, 2, 3, 4, 5, 6] | Specifies which headlines are supported. |
## Commands
@@ -51,7 +52,7 @@ export default {
return {
editor: new Editor({
extensions: [
new Heading({
Heading({
levels: [1, 2],
}),
],

View File

@@ -2,7 +2,9 @@
Enables you to use the `<hr>` HTML tag in the editor.
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
@@ -39,7 +41,7 @@ export default {
return {
editor: new Editor({
extensions: [
new HorizontalRule(),
HorizontalRule(),
],
content: `
<p>Some text.</p>

View File

@@ -6,7 +6,9 @@ The extension will generate the corresponding `<em>` HTML tags when reading cont
:::
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |

View File

@@ -3,5 +3,6 @@ Enables you to use the `<a>` HTML tag in the editor.
## Options
| Option | Type | Default | Description |
| ------ | ---- | ---- | ----- |
| openOnClick | Boolean | true | Specifies if links will be opened on click. |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
| openOnClick | Boolean | true | Specifies if links will be opened on click. |

View File

@@ -3,4 +3,9 @@ Enables you to use the `<li>` HTML tag in the editor.
::: warning Restrictions
This extensions is intended to be used with the `BulletList` or `OrderedList` extension.
:::
:::
## Options
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |

View File

@@ -6,7 +6,9 @@ This extensions is intended to be used with the `ListItem` extension.
:::
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
@@ -43,7 +45,7 @@ export default {
return {
editor: new Editor({
extensions: [
new OrderedList(),
OrderedList(),
],
content: `
<ol>

View File

@@ -1,2 +1,19 @@
# Paragraph
Enables you to use paragraphs in the editor.
Yes, the schema is very strict. Without this extension you wont even be able to use paragraphs in the editor.
## Options
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
*None*
## Keybindings
*None*
## Source Code
[packages/extension-paragraph/](https://github.com/ueberdosis/tiptap-next/blob/main/packages/extension-paragraph/)
## Usage
<demo name="Extensions/Paragraph" highlight="11,29" />

View File

@@ -2,7 +2,9 @@
Enables you to use the `<s>` HTML tag in the editor.
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
@@ -40,7 +42,7 @@ export default {
return {
editor: new Editor({
extensions: [
new Strike(),
Strike(),
],
content: `
<p><s>That's strikethrough.</s></p>

View File

@@ -7,7 +7,7 @@ This extensions is intended to be used with the `TodoList` extension.
## Options
| Option | Type | Default | Description |
| ------ | ---- | ---- | ----- |
| ------ | ---- | ------- | ----------- |
| nested | Boolean | false | Specifies if you can nest todo lists. |
## Commands

View File

@@ -43,10 +43,10 @@ export default {
return {
editor: new Editor({
extensions: [
new TodoItem({
TodoItem({
nested: true,
}),
new TodoList(),
TodoList(),
],
content: `
<ul data-type="todo_list">

View File

@@ -2,7 +2,9 @@
Enables you to use the `<u>` HTML tag in the editor.
## Options
*None*
| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| class | string | | Add a custom class to the rendered HTML tag. |
## Commands
| Command | Options | Description |
@@ -40,7 +42,7 @@ export default {
return {
editor: new Editor({
extensions: [
new Underline(),
Underline(),
],
content: `
<p><u>This is underlined.</u></p>

View File

@@ -13,9 +13,9 @@ import Text from '@tiptap/extension-text'
const editor = new Editor({
extensions: [
new Document,
new Paragraph,
new Text,
Document(),
Paragraph(),
Text(),
// add more extensions here
])
})
@@ -33,9 +33,9 @@ import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
const schema = getSchema([
new Document,
new Paragraph,
new Text,
Document(),
Paragraph(),
Text(),
// add more extensions here
])
```

View File

@@ -1,3 +1,3 @@
# Focus
<demo name="Examples/Focus" highlight="18,43-46,48" />
<demo name="Examples/Focus" highlight="13,33-36,38" />

View File

@@ -1,80 +0,0 @@
# Roadmap
## Tasks
1. Refactoring the API & Extension Manager
2. Improve testing: Add editor instance to the DOM element
3. Building the first batch of basic extensions (bold, italic), writing tests
4. Building more complex examples from the extensions
## New features
* generate schema without initializing tiptap, to make SSR easier (e. g. `getSchema([new Doc(), new Paragraph()])`)
## Requested features
* Basic Styling
* https://github.com/ueberdosis/tiptap/issues/507
* Support vor Vue.js 3
* Easily add custom classes to everything
* https://github.com/ueberdosis/tiptap/discussions/817
* Text snippets
* https://github.com/ueberdosis/tiptap/issues/737
* Markdown Support
## Requested extensions
* Alignment
* https://github.com/ueberdosis/tiptap/pull/544
* Font color
* Font family
* Font size
* Created embed from pasted YouTube URL
* Superscript/Subscript
* https://github.com/ueberdosis/tiptap/discussions/813
* Math Support
* https://github.com/ueberdosis/tiptap/issues/179
* https://github.com/ueberdosis/tiptap/issues/698
* Resizeable Images
* https://gist.github.com/zachjharris/a5442efbdff11948d085b6b1406dfbe6
## Ideas
* A `@tiptap/extensions` package would be helpful to make imports easier.
* Add more shorcuts:
* Ctrl+I → Italic ✅
* Ctrl+B → Bold ✅
* Ctrl+K → Link (Medium, Tumblr, Slack, Google Docs, Word)
* Ctrl+Shift+K → Code (Slack)
* Shift+Enter → Line break
* Ctrl+Shift+X → Strikethrough (Slack)
* Alt+Shift+5 → Strikethrough (Google Docs)
* Ctrl+Shift+6 → Strikethrough (Tumblr)
* Ctrl+Alt+0 → Paragraph (Google Docs)
* Ctrl+Alt+1 to 6 → Heading (Google Docs, Word, ~Medium, ~Slack)
* Ctrl+Shift+2 → Heading (Tumblr)
* Ctrl+Shift+7 → Ordered list (Google Docs, Slack, Tumblr)
* Ctrl+Shift+8 → Unordered list (Google Docs, Slack, Tumblr)
* Tab, Shift+Tab → Increase / decrease nesting in lists
* Ctrl+], Ctrl+[ → Same as above (when Tab needs to be used)
* Ctrl+Shift+9 → Blockquote (Tumblr)
* Ctrl+Alt+K → Code block (Slack)
* Ctrl+R → Horizontal ruler (Stack Overflow)
* Markdown shortcuts
* #+Space → Heading (the number of # determines the header level)
* *+Space, -+Space → Unordered list
* 1.+Space → Ordered list
* >+Space → Blockquote
* ```+Space → Code block
* ---- → Horizontal ruler
* ![] → Embedded resource (not part of Slack, but would it not be fancy?)
* :emoji: → Emoji (based on the name). A nice-to-have, most certainly.
* General shortcuts
* Ctrl+C, Ctrl+X, Ctrl+V: copy, cut, paste
* Ctrl+Z, Ctrl+Shift+Z, Ctrl+Y: undo, redo
* Ctrl+Backspace: delete previous word
* Ctrl+Delete: delete next word
* Ctrl+Home, Ctrl+End: go to the start / end of the whole document
* Ctrl+F, Ctrl+G: find, find next occurrence
* Ctrl+S: if there is no auto-saving, this should save the document
* Ctrl+/: show shortcuts (Medium, Slack)

View File

@@ -1,3 +0,0 @@
# Upgrade Guide
## Upgrading from 1.x to 2.x

View File

@@ -0,0 +1,11 @@
# Contributing
## What kind of contributions are welcome
## What kind of contributions wont be merged
## How to send your first Pull Request
## Code style
## Testing

View File

@@ -2,15 +2,15 @@
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.
## Vanilla JavaScript
## Plain 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 the tiptap core with other frameworks not mentioned here.
```bash
# Use npm
# With npm
npm install @tiptap/core @tiptap/starter-kit
# Or: Use Yarn
# Or: With Yarn
yarn add @tiptap/core @tiptap/starter-kit
```
@@ -18,11 +18,11 @@ Great, that should be enough to start. Here is the most essential code you need
```js
import { Editor } from '@tiptap/core'
import extensions from '@tiptap/starter-kit'
import defaultExtensions from '@tiptap/starter-kit'
new Editor({
element: document.getElementsByClassName('element'),
extensions: extensions(),
extensions: defaultExtensions(),
content: '<p>Your content.</p>',
})
```
@@ -32,10 +32,10 @@ new Editor({
To use tiptap with Vue.js (and tools that are based on Vue.js) install the Vue.js adapter in your project:
```bash
# Using npm
# With npm
npm install @tiptap/vue @tiptap/vue-starter-kit
# Using Yarn
# Or: With Yarn
yarn add @tiptap/vue @tiptap/vue-starter-kit
```

View File

@@ -0,0 +1,3 @@
# Roadmap
See https://github.com/ueberdosis/tiptap-next/projects/1

View File

@@ -0,0 +1,3 @@
# Sponsoring
https://github.com/sponsors/ueberdosis

View File

@@ -0,0 +1,35 @@
# Upgrade Guide
## Reasons to upgrade to tiptap 2.x
* TypeScript: auto complete, less bugs, generated API documentation
* Amazing documentation with 100+ pages
* Active maintenance, no more updates to 1.x
* Tons of new extensions planned
* Less bugs, tested code based
## 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 should do:
### New document type
**We renamed the default `Document` type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name.
```js
import Document from '@tiptap/extension-document'
const CustomDocument = Document.name('doc').create()
new Editor({
extensions: [
CustomDocument(),
]
})
```
### New extension API
In case youve built some custom extensions for your project, youll 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. Its just different how you register them.
```js
const CustomExtension =
```

View File

@@ -1,14 +1,20 @@
- title: General
- title: Overview
items:
- title: Introduction
link: /
- title: Installation
link: /general/installation
link: /overview/installation
- title: Upgrade Guide
link: /general/upgrade-guide
link: /overview/upgrade-guide
draft: true
- title: Contributing
link: /overview/contributing
draft: true
- title: Sponsoring
link: /overview/sponsoring
draft: true
- title: Roadmap
link: /general/roadmap
link: /overview/roadmap
draft: true
- title: Guide
@@ -40,62 +46,62 @@
link: /examples/basic
- title: Simple
link: /examples/simple
- title: Menu Bubble
link: /examples/menu-bubble
draft: true
- title: Floating Menu
link: /examples/floating-menu
draft: true
- title: Links
link: /examples/links
draft: true
- title: Images
link: /examples/images
draft: true
- title: Hiding Menu Bar
link: /examples/hiding-menu-bar
draft: true
- title: Todo List
link: /examples/todo-list
draft: true
- title: Tables
link: /examples/tables
draft: true
- title: Search and Replace
link: /examples/search-and-replace
draft: true
- title: Suggestions
link: /examples/suggestions
draft: true
# - title: Menu Bubble
# link: /examples/menu-bubble
# draft: true
# - title: Floating Menu
# link: /examples/floating-menu
# draft: true
# - title: Links
# link: /examples/links
# draft: true
# - title: Images
# link: /examples/images
# draft: true
# - title: Hiding Menu Bar
# link: /examples/hiding-menu-bar
# draft: true
# - title: Todo List
# link: /examples/todo-list
# draft: true
# - title: Tables
# link: /examples/tables
# draft: true
# - title: Search and Replace
# link: /examples/search-and-replace
# draft: true
# - title: Suggestions
# link: /examples/suggestions
# draft: true
- title: Markdown Shortcuts
link: /examples/markdown-shortcuts
- title: Code Highlighting
link: /examples/code-highlighting
draft: true
# - title: Code Highlighting
# link: /examples/code-highlighting
# draft: true
- title: History
link: /examples/history
- title: Read-Only
link: /examples/read-only
- title: Embeds
link: /examples/embeds
draft: true
- title: Placeholder
link: /examples/placeholder
draft: true
# - title: Embeds
# link: /examples/embeds
# draft: true
# - title: Placeholder
# link: /examples/placeholder
# draft: true
- title: Focus
link: /examples/focus
- title: Collaboration
link: /examples/collaboration
draft: true
- title: Title
link: /examples/title
draft: true
- title: Trailing Paragraph
link: /examples/trailing-paragraph
draft: true
- title: Drag Handle
link: /examples/drag-handle
draft: true
# - title: Collaboration
# link: /examples/collaboration
# draft: true
# - title: Title
# link: /examples/title
# draft: true
# - title: Trailing Paragraph
# link: /examples/trailing-paragraph
# draft: true
# - title: Drag Handle
# link: /examples/drag-handle
# draft: true
- title: Export HTML or JSON
link: /examples/export-html-or-json
@@ -128,7 +134,6 @@
# draft: true
- title: Document
link: /api/extensions/document
draft: true
- title: Hardbreak
link: /api/extensions/hard-break
draft: true
@@ -156,7 +161,6 @@
draft: true
- title: Paragraph
link: /api/extensions/paragraph
draft: true
# - title: Placeholder
# link: /api/extensions/placeholder
# draft: true