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

add new example, update content

Browse Source
This commit is contained in:
Hans Pagel
2020-10-30 16:13:47 +01:00
parent 4482ad00d5
commit e7c7ea16c7
16 changed files with 236 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
docs/src/demos/Examples/Formatting/index.vue Normal file
View File

@@ -0,0 +1,97 @@
<template>
<div>
<div v-if="editor">
<button @click="editor.chain().focus().bold().run()" :class="{ 'is-active': editor.isActive('bold') }">
bold
</button>
<button @click="editor.chain().focus().italic().run()" :class="{ 'is-active': editor.isActive('italic') }">
italic
</button>
<button @click="editor.chain().focus().heading({ level: 1 }).run()" :class="{ 'is-active': editor.isActive('heading', { level: 1 }) }">
h1
</button>
<button @click="editor.chain().focus().heading({ level: 2 }).run()" :class="{ 'is-active': editor.isActive('heading', { level: 2 }) }">
h2
</button>
<button @click="editor.chain().focus().heading({ level: 3 }).run()" :class="{ 'is-active': editor.isActive('heading', { level: 3 }) }">
h3
</button>
<button @click="editor.chain().focus().paragraph().run()" :class="{ 'is-active': editor.isActive('paragraph') }">
paragraph
</button>
<button @click="editor.chain().focus().textAlign('left').run()">
left
</button>
<button @click="editor.chain().focus().textAlign('center').run()">
center
</button>
<button @click="editor.chain().focus().textAlign('right').run()">
right
</button>
</div>
<editor-content :editor="editor" />
</div>
</template>
<script>
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 Heading from '@tiptap/extension-heading'
import Bold from '@tiptap/extension-bold'
import Italic from '@tiptap/extension-italic'
import TextAlign from '@tiptap/extension-text-align'
import HardBreak from '@tiptap/extension-hard-break'
export default {
components: {
EditorContent,
},
data() {
return {
editor: null,
}
},
mounted() {
this.editor = new Editor({
extensions: [
Document(),
Paragraph(),
Text(),
Heading({
level: [1, 2, 3],
}),
Bold(),
Italic(),
TextAlign(),
HardBreak(),
],
content: `
<h2>Cyndi Lauper – Girls Just Want to Have Fun</h2>
<p>I come home in the morning light
My mother says, “When you gonna live your life right?”
Oh mother dear we’re not the fortunate ones
And girls, they wanna have fun
Oh girls just want to have fun</p>
<p>The phone rings in the middle of the night
My father yells, "What you gonna do with your life?"
Oh daddy dear, you know you’re still number one
But girls, they wanna have fun
Oh girls just want to have</p>
<p>That’s all they really want
Some fun
When the working day is done
Oh girls, they wanna have fun
Oh girls just wanna have fun (girls, they wanna, wanna have fun, girls wanna have)</p>
`,
})
},
beforeDestroy() {
this.editor.destroy()
},
}
</script>

24
docs/src/demos/Extensions/Paragraph/index.vue
View File

@@ -11,6 +11,26 @@ import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
const CustomParagraph = Paragraph.extend({
addAttributes() {
return {
color: {
default: null,
parseHTML: element => {
return {
color: element.getAttribute('data-color'),
}
},
renderHTML: attributes => {
return {
style: `color: ${attributes.color}`,
}
},
},
}
},
})
export default {
components: {
EditorContent,
@@ -26,11 +46,11 @@ export default {
this.editor = new Editor({
extensions: [
Document(),
Paragraph(),
CustomParagraph(),
Text(),
],
content: `
<p>The Paragraph extension is not required, but it’s very likely you want to use it. It’s needed to write paragraphs of text. 🤓</p>
<p data-color="blue">The Paragraph extension is not required, but it’s very likely you want to use it. It’s needed to write paragraphs of text. 🤓</p>
`,
})
},

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

@@ -4,7 +4,7 @@
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`). That’s 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.
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.
:::
## Installation

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

@@ -2,7 +2,7 @@
Yes, the schema is very strict. Without this extension you won’t even be able to use paragraphs in the editor.
:::warning Breaking Change from 1.x → 2.x
Tiptap 1 tried to hide that node from you, but it has always been there. You have to explicitly import it from now on (or use `defaultExtensions()`).
tiptap 1 tried to hide that node from you, but it has always been there. You have to explicitly import it from now on (or use `defaultExtensions()`).
:::
## Installation

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

@@ -2,7 +2,7 @@
**The `Text` extension is required**, at least if you want to work with text of any kind and that’s very likely. This extension is a little bit different, it doesn’t even render HTML. It’s plain text, that’s all.
:::warning Breaking Change from 1.x → 2.x
Tiptap 1 tried to hide that node from you, but it has always been there. You have to explicitly import it from now on (or use `defaultExtensions()`).
tiptap 1 tried to hide that node from you, but it has always been there. You have to explicitly import it from now on (or use `defaultExtensions()`).
:::
## Installation

2
docs/src/docPages/api/keyboard-shortcuts.md
View File

@@ -3,7 +3,7 @@
## toc
## Introduction
Tiptap comes with sensible keyboard shortcut defaults. Depending on what you want to use it for, you’ll probably want to change those keyboard shortcuts to your liking. Let’s have a look at what we defined for you, and show you how to change it then!
tiptap comes with sensible keyboard shortcut defaults. Depending on what you want to use it for, you’ll probably want to change those keyboard shortcuts to your liking. Let’s have a look at what we defined for you, and show you how to change it then!
## Predefined keyboard shortcuts
Most of the core extensions register their own keyboard shortcuts. Depending on what set of extension you use, not all of the below listed keyboard shortcuts work for your editor.

50
docs/src/docPages/api/schema.md
View File

@@ -141,3 +141,53 @@ We needed to do the same thing in PHP at some point, so we published libraries t
* [ueberdosis/prosemirror-php](https://github.com/ueberdosis/prosemirror-php) (PHP)
* [ueberdosis/prosemirror-to-html](https://github.com/ueberdosis/prosemirror-to-html) (PHP)
* [ueberdosis/html-to-prosemirror](https://github.com/ueberdosis/html-to-prosemirror) (PHP)
### Node Schema
#### Content
> The content expression for this node, as described in the schema guide. When not given, the node does not allow any content.
#### Marks
> The marks that are allowed inside of this node. May be a space-separated string referring to mark names or groups, "_" to explicitly allow all marks, or "" to disallow marks. When not given, nodes with inline content default to allowing all marks, other nodes default to not allowing marks.
#### Group
> The group or space-separated groups to which this node belongs, which can be referred to in the content expressions for the schema.
#### Inline
> Should be set to true for inline nodes. (Implied for text nodes.)
#### Atom
> Can be set to true to indicate that, though this isn't a leaf node, it doesn't have directly editable content and should be treated as a single unit in the view.
#### Selectable
> Controls whether nodes of this type can be selected as a node selection. Defaults to true for non-text nodes.
#### Draggable
> Determines whether nodes of this type can be dragged without being selected. Defaults to false.
#### Code
> Can be used to indicate that this node contains code, which causes some commands to behave differently.
#### Defining
> Determines whether this node is considered an important parent node during replace operations (such as paste). Non-defining (the default) nodes get dropped when their entire content is replaced, whereas defining nodes persist and wrap the inserted content. Likewise, in inserted content the defining parents of the content are preserved when possible. Typically, non-default-paragraph textblock types, and possibly list items, are marked as defining.
#### Isolating
> When enabled (default is false), the sides of nodes of this type count as boundaries that regular editing operations, like backspacing or lifting, won't cross. An example of a node that should probably have this enabled is a table cell.
### Mark Schema
#### Inclusive
> Whether this mark should be active when the cursor is positioned at its end (or at its start when that is also the start of the parent node). Defaults to true.
#### Excludes
> Determines which other marks this mark can coexist with. Should be a space-separated strings naming other marks or groups of marks When a mark is added to a set, all marks that it excludes are removed in the process. If the set contains any mark that excludes the new mark but is not, itself, excluded by the new mark, the mark can not be added an the set. You can use the value "_" to indicate that the mark excludes all marks in the schema.
> Defaults to only being exclusive with marks of the same type. You can set it to an empty string (or any string not containing the mark's own name) to allow multiple marks of a given type to coexist (as long as they have different attributes).
#### Group
> The group or space-separated groups to which this mark belongs.
#### Spanning
> Determines whether marks of this type can span multiple adjacent nodes when serialized to DOM/HTML. Defaults to true.

3
docs/src/docPages/examples/formatting.md Normal file
View File

@@ -0,0 +1,3 @@
# Formatting
<demo name="Examples/Formatting" />

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

@@ -35,12 +35,12 @@ new Editor({
The same applies to every aspect of an existing extension, except to the name. Let’s look at all the things that you can change through the extend method. We focus on one aspect in every example, but you can combine all those examples and change multiple aspects in one `extend()` call too.
### Name
The extension name is used in a whole lot of places and changing it isn’t too easy. If you want to change the name of an extension, it’s recommended to copy the whole extension and change the name in all occurrences.
The extension name is used in a whole lot of places and changing it isn’t too easy. If you want to change the name of an existing extension, we would recommended to copy the whole extension and change the name in all occurrences.
The extension name is also part of the JSON. If you [store your content as JSON](http://localhost:3000/guide/store-content#option-1-json), you need to change the name in there too.
The extension name is also part of the JSON. If you [store your content as JSON](/guide/store-content#option-1-json), you need to change the name there too.
### Settings
All settings can be overwritten through the extension anyway, but if you want to change the defaults, for example to provide a library on top of tiptap for other developers, you can do it like that:
All settings can be configured through the extension anyway, but if you want to change the default settings, for example to provide a library on top of tiptap for other developers, you can do it like that:
```js
import Heading from '@tiptap/extension-heading'
@@ -52,17 +52,13 @@ const CustomHeading = Heading.extend({
})
```
### Node Schema
Tiptap works with a [strict schema](/api/schema), which configures how the content can be structured, nested, how it behaves and many more things. You can change all aspects of the schema for existing extensions. Let’s walk through a few common use cases.
### Schema
tiptap works with a strict schema, which configures how the content can be structured, nested, how it behaves and many more things. You [can change all aspects of the schema](/api/schema) for existing extensions. Let’s walk through a few common use cases.
The default `Blockquote` extension can wrap other nodes, like headings. If you want to allow nothing but paragraphs in your blockquotes, this is how you could achieve it:
#### Content
> The content expression for this node, as described in the schema guide. When not given, the node does not allow any content.
```js
// blockquotes include paragraphs only
// Blockquotes must only include paragraphs
import Blockquote from '@tiptap/extension-blockquote'
const CustomBlockquote = Blockquote.extend({
@@ -70,25 +66,7 @@ const CustomBlockquote = Blockquote.extend({
})
```
#### Marks
> The marks that are allowed inside of this node. May be a space-separated string referring to mark names or groups, "_" to explicitly allow all marks, or "" to disallow marks. When not given, nodes with inline content default to allowing all marks, other nodes default to not allowing marks.
#### Group
> The group or space-separated groups to which this node belongs, which can be referred to in the content expressions for the schema.
#### Inline
> Should be set to true for inline nodes. (Implied for text nodes.)
#### Atom
> Can be set to true to indicate that, though this isn't a leaf node, it doesn't have directly editable content and should be treated as a single unit in the view.
#### Selectable
> Controls whether nodes of this type can be selected as a node selection. Defaults to true for non-text nodes.
#### Draggable
> Determines whether nodes of this type can be dragged without being selected. Defaults to false.
The schema even allows to make your nodes draggable, that’s what the `draggable` option is for, which defaults to `false`. Here is an example for draggable paragraphs:
The schema even allows to make your nodes draggable, that’s what the `draggable` option is for, which defaults to `false`.
```js
// Draggable paragraphs
@@ -99,36 +77,15 @@ const CustomParagraph = Paragraph.extend({
})
```
#### Code
> Can be used to indicate that this node contains code, which causes some commands to behave differently.
#### Defining
> Determines whether this node is considered an important parent node during replace operations (such as paste). Non-defining (the default) nodes get dropped when their entire content is replaced, whereas defining nodes persist and wrap the inserted content. Likewise, in inserted content the defining parents of the content are preserved when possible. Typically, non-default-paragraph textblock types, and possibly list items, are marked as defining.
#### Isolating
> When enabled (default is false), the sides of nodes of this type count as boundaries that regular editing operations, like backspacing or lifting, won't cross. An example of a node that should probably have this enabled is a table cell.
### Mark Schema
#### Inclusive
> Whether this mark should be active when the cursor is positioned at its end (or at its start when that is also the start of the parent node). Defaults to true.
#### Excludes
> Determines which other marks this mark can coexist with. Should be a space-separated strings naming other marks or groups of marks When a mark is added to a set, all marks that it excludes are removed in the process. If the set contains any mark that excludes the new mark but is not, itself, excluded by the new mark, the mark can not be added an the set. You can use the value "_" to indicate that the mark excludes all marks in the schema.
> Defaults to only being exclusive with marks of the same type. You can set it to an empty string (or any string not containing the mark's own name) to allow multiple marks of a given type to coexist (as long as they have different attributes).
#### Group
> The group or space-separated groups to which this mark belongs.
#### Spanning
> Determines whether marks of this type can span multiple adjacent nodes when serialized to DOM/HTML. Defaults to true.
That’s just two tiny examples, but [the underlying ProseMirror schema](https://prosemirror.net/docs/ref/#model.SchemaSpec) is really powerful. You should definitely read the documentation to understand all the nifty details.
### Attributes
You can use attributes to store additional information in the content. Let’s say you want to extend the default paragraph extension with a color attribute to allow paragraphs to have different colors:
You can use attributes to store additional information in the content. Let’s say you want to extend the default paragraph extension to enable paragraphs to have different colors:
```js
const CustomParagraph = Paragraph.extend({
addAttributes() {
// Return an object with attribute configuration
return {
color: {
default: 'pink',
@@ -143,7 +100,9 @@ const CustomParagraph = Paragraph.extend({
That’s already enough to tell tiptap about the new attribute, and set `'pink'` as the default value. All attributes will be rendered as a data-attributes by default, and parsed as data-attributes from the content.
Let’s stick with the color example and assume you’ll probably want to add an inline style to actually color the text. Add a `renderHTML` function and return the attributes that should be added to the rendered HTML. This examples adds a style attribute based on the value of color:
Let’s stick with the color example and assume you’ll want to add an inline style to actually color the text. With the `renderHTML` function you can return HTML attributes which will be rendered in the output.
This examples adds a style HTML attribute based on the value of color:
```js
const CustomParagraph = Paragraph.extend({
@@ -151,7 +110,9 @@ const CustomParagraph = Paragraph.extend({
return {
color: {
default: null,
// Take the attribute values
renderHTML: attributes => {
// … and return an object with HTML attributes.
return {
style: `color: ${attributes.color}`,
}
@@ -173,11 +134,13 @@ const CustomParagraph = Paragraph.extend({
return {
color: {
default: null,
// Customize the HTML parsing (for example, to load the initial content)
parseHTML: element => {
return {
color: element.getAttribute('data-my-fancy-color-attribute'),
}
},
// … and customize the HTML rendering.
renderHTML: attributes => {
return {
'data-my-fancy-color-attribute': atttributes.color,
@@ -194,7 +157,39 @@ const CustomParagraph = Paragraph.extend({
```
### Global Attributes
> TextAlign
Attributes can be applied to multiple extensions at once. That’s useful for text alignment, line height, color, font family, and other styling related attributes.
Take a closer look at the full source code of the [`TextAlign`](/api/extensions/text-align) extension to see a more complex example. But here is how it works in a nutshell:
```js
import { createExtension } from '@tiptap/core'
const TextAlign = createExtension({
addGlobalAttributes() {
return [
{
// Extend the following extensions
types: [
'heading',
'paragraph',
],
// … with those attributes
attributes: {
textAlign: {
default: 'left',
renderHTML: attributes => ({
style: `text-align: ${attributes.textAlign}`,
}),
parseHTML: element => ({
textAlign: element.style.textAlign || 'left',
}),
},
},
},
]
},
})
```
### Parse HTML
> Associates DOM parser information with this mark (see the corresponding node spec field). The mark field in the rules is implied.

2
docs/src/docPages/guide/create-your-editor.md
View File

@@ -18,7 +18,7 @@ You might wonder what features tiptap supports out of the box. In the above exam
* [List of available commands](/api/commands)
## Configure extensions
You are free to choose which parts of tiptap you want to use. Tiptap has support for different nodes (paragraphs, blockquotes, tables and many more) and different marks (bold, italic, links). If you want to explicitly configure what kind of nodes and marks are allowed and which are not allowed, you can configure those.
You are free to choose which parts of tiptap you want to use. tiptap has support for different nodes (paragraphs, blockquotes, tables and many more) and different marks (bold, italic, links). If you want to explicitly configure what kind of nodes and marks are allowed and which are not allowed, you can configure those.
Note that `Document`, `Paragraph` and `Text` are required. Otherwise you won’t be able to add any plain text.

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

@@ -3,7 +3,7 @@
## toc
## Introduction
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: 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:

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

@@ -19,7 +19,7 @@ yarn add @tiptap/vue @tiptap/vue-starter-kit
The `@tiptap/vue-starter-kit` includes a few basics you would probably need anyway. Cool, you have got everything in place to set up tiptap! 🙌
## 2. Create a new component
Create a new Vue component (you can call it `<Tiptap />`) and add the following content. This is the fastest way to get tiptap up and running with Vue.js. It will give you a very basic version of tiptap, without any buttons. No worries, you will be able to add more functionality soon.
Create a new Vue component (you can call it `<tiptap />`) and add the following content. This is the fastest way to get tiptap up and running with Vue.js. It will give you a very basic version of tiptap, without any buttons. No worries, you will be able to add more functionality soon.
<demo name="Guide/GettingStarted" />

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

@@ -19,9 +19,9 @@ Although tiptap tries to hide most of the complexity of ProseMirror, it’s buil
**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 or Vue.js. That makes it even possible to write a renderer for React, Svelte and others.
**Framework-agnostic.** We don’t care what framework you use. tiptap is ready to be used with plain JavaScript or Vue.js. That makes it even possible to write a renderer for React, Svelte and others.
**TypeScript.** Tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE supports that), helps to find bugs early and makes it possible to generate [a complete API documentation](#) on top of the extensive human written documentation.
**TypeScript.** tiptap 2 is written in TypeScript. That gives you a nice autocomplete for the API (if your IDE supports that), 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)
@@ -33,4 +33,4 @@ Although tiptap tries to hide most of the complexity of ProseMirror, it’s buil
- [and many more →](https://github.com/ueberdosis/tiptap/network/dependents?package_id=UGFja2FnZS0xMzE5OTg0ODc%3D)
## License
Tiptap is licensed under MIT, so you’re free to whatever you want. Anyway, we kindly ask you to [become a sponsor](https://github.com/sponsors/ueberdosis) on GitHub to fund the development, maintenance and support of tiptap.
tiptap is licensed under MIT, so you’re free to whatever you want. Anyway, we kindly ask you to [become a sponsor](https://github.com/sponsors/ueberdosis) on GitHub to fund the development, maintenance and support of tiptap.

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

@@ -3,7 +3,7 @@
## toc
## Introduction
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:
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:
## Welcome examples
* Failing regression tests as bug reports

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

@@ -18,7 +18,7 @@ The new API will look pretty familiar too you, but there are a ton of changes th
…
### 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 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.
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'

2
docs/src/links.yaml
View File

@@ -24,6 +24,8 @@
# - title: Floating Menu
# link: /examples/floating-menu
# draft: true
- title: Formatting
link: /examples/formatting
- title: Links
link: /examples/links
# - title: Images