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

docs: make all extenion settings a list

Browse Source
This commit is contained in:
Hans Pagel
2021-10-02 01:20:09 +02:00
parent 4487fb0d75
commit 9ed883edd4
21 changed files with 586 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/api/extensions/bubble-menu.md
View File

@@ -15,12 +15,32 @@ yarn add @tiptap/extension-bubble-menu
```
## Settings
| Option | Type | Default | Description |
| ------------ | -------------------- | -------------- | ----------------------------------------------------------------------- |
| element | `HTMLElement` | `null` | The DOM element that contains your menu. |
| tippyOptions | `Object` | `{}` | [Options for tippy.js](https://atomiks.github.io/tippyjs/v6/all-props/) |
| pluginKey | `string \| PluginKey` | `'bubbleMenu'` | The key for the underlying ProseMirror plugin. |
| shouldShow | `(props) => boolean` | | Controls whether the menu should be shown or not. |
### element
The DOM element that contains your menu.
Type: `HTMLElement`
Default: `null`
### tippyOptions
Under the hood, the `BubbleMenu` uses [tippy.js](https://atomiks.github.io/tippyjs/v6/all-props/). You can directly pass options to it.
Type: `Object`
Default: `{}`
### pluginKey
The key for the underlying ProseMirror plugin. Make sure to use different keys if you add more than one instance.
Type: `string | PluginKey`
Default: `'bubbleMenu'`
### shouldShow
A callback to control whether the menu should be shown or not.
Type: `(props) => boolean`
## Source code
[packages/extension-bubble-menu/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-bubble-menu/)

15
docs/api/extensions/character-count.md
View File

@@ -14,9 +14,18 @@ yarn add @tiptap/extension-character-count
```
## Settings
| Option | Type | Default | Description |
| ------ | -------- | ------- | -------------------------------------------------------- |
| limit | `Number` | `0` | The maximum number of characters that should be allowed. |
### limit
The maximum number of characters that should be allowed. |
Default: `0`
```js
CharacterCount.configure({
limit: 240,
})
```
## Source code
[packages/extension-character-count/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-character-count/)

28
docs/api/extensions/collaboration-cursor.md
View File

@@ -22,16 +22,28 @@ yarn add @tiptap/extension-collaboration-cursor
This extension requires the [`Collaboration`](/api/extensions/collaboration) extension.
## Settings
| Option | Type | Default | Description |
| -------- | ---------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| provider | `Object` | `null` | A Y.js network connection, for example a [y-websocket](https://github.com/yjs/y-websocket) instance. |
| user | `Object` | `{ user: null, color: null }` | Attributes of the current user, assumes to have a name and a color, but can be used with any attribute. |
| render | `Function` | … | A render function for the cursor, look at [the extension source code](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-collaboration-cursor/) for an example. |
### provider
A Y.js network provider, for example a [y-websocket](https://github.com/yjs/y-websocket) instance.
Default: `null`
### user
Attributes of the current user, assumes to have a name and a color, but can be used with any attribute. The values are synced with all other connected clients.
Default: `{ user: null, color: null }`
### render
A render function for the cursor, look at [the extension source code](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-collaboration-cursor/) for an example.
## Commands
| Command | Parameters | Description |
| ------- | ---------- | ------------------------------------------------------------------------------------------------ |
| user | attributes | An object with the attributes of the current user, by default it expects a `name` and a `color`. |
### user()
An object with the attributes of the current user. It expects a `name` and a `color`, but you can add additional fields, too.
```js
editor.commands.user({ name: 'Philipp Kühn', color: '#000000' })
```
## Source code
[packages/extension-collaboration-cursor/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-collaboration-cursor/)

57
docs/api/extensions/collaboration.md
View File

@@ -20,17 +20,56 @@ yarn add @tiptap/extension-collaboration yjs y-websocket
```
## Settings
| Option | Type | Default | Description |
| -------- | -------- | ----------- | --------------------------------------------------------------------------------------- |
| document | `Object` | `null` | An initialized Y.js document. |
| field | `String` | `'default'` | Name of a Y.js fragment, can be changed to sync multiple fields with one Y.js document. |
| fragment | `Object` | `null` | A raw Y.js fragment, can be used instead of `document` and `field`. |
### document
An initialized Y.js document.
Default: `null`
```js
Collaboration.configure({
document: new Y.Doc(),
})
```
### field
Name of a Y.js fragment, can be changed to sync multiple fields with one Y.js document.
Default: `'default'`
```js
Collaboration.configure({
document: new Y.Doc(),
field: 'title',
})
```
### fragment
A raw Y.js fragment, can be used instead of `document` and `field`.
Default: `null`
```js
Collaboration.configure({
fragment: new Y.Doc().getXmlFragment('body'),
})
```
## Commands
| Command | Parameters | Description |
| ------- | ---------- | --------------------- |
| undo | — | Undo the last change. |
| redo | — | Redo the last change. |
The `Collboration` extension comes with its own history extension. Make sure to disable the default extension, if you’re working with the `StarterKit`.
### undo()
Undo the last change.
```js
editor.commands.undo()
```
### redo()
Redo the last change.
```js
editor.commands.redo()
```
## Keyboard shortcuts
| Command | Windows/Linux | macOS |

31
docs/api/extensions/color.md
View File

@@ -16,14 +16,33 @@ yarn add @tiptap/extension-text-style @tiptap/extension-color
This extension requires the [`TextStyle`](/api/marks/text-style) mark.
## Settings
| Option | Type | Default | Description |
| ------ | ------- | --------------- | ------------------------------------------------------------------------ |
| types | `Array` | `['textStyle']` | A list of marks to which the font family attribute should be applied to. |
### types
A list of marks to which the color attribute should be applied to.
Default: `['textStyle']`
```js
Color.configure({
types: ['textStyle'],
})
```
## Commands
| Command | Parameters | Description |
| ------- | ---------- | -------------------------------------------- |
| color | color | Applies the given font color as inline style |
### setColor()
Applies the given font color as inline style.
```js
editor.commands.setColor('#ff0000')
```
### unsetColor()
Removes any font color.
```js
editor.commands.unsetColor()
```
## Source code
[packages/extension-color/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-color/)

36
docs/api/extensions/dropcursor.md
View File

@@ -16,11 +16,37 @@ yarn add @tiptap/extension-dropcursor
```
## Settings
| Option | Type | Default | Description |
| ------ | -------- | ---------------- | --------------------------------------------------------------------- |
| color | `String` | `'currentcolor'` | Color of the dropcursor. |
| width | `Number` | `1` | Width of the dropcursor. |
| class | `String` | – | One or multiple CSS classes that should be applied to the dropcursor. |
### color
Color of the dropcursor.
Default: `'currentcolor'`
```js
Dropcursor.configure({
color: '#ff0000'
})
```
### width
Width of the dropcursor.
Default: `1`
```js
Dropcursor.configure({
width: 2,
})
```
### class
One or multiple CSS classes that should be applied to the dropcursor.
```js
Dropcursor.configure({
class: 'my-custom-class',
})
```
## Source code
[packages/extension-dropcursor/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-dropcursor/)

32
docs/api/extensions/floating-menu.md
View File

@@ -13,12 +13,32 @@ yarn add @tiptap/extension-floating-menu
```
## Settings
| Option | Type | Default | Description |
| ------------ | -------------------- | ---------------- | ----------------------------------------------------------------------- |
| element | `HTMLElement` | `null` | The DOM element of your menu. |
| tippyOptions | `Object` | `{}` | [Options for tippy.js](https://atomiks.github.io/tippyjs/v6/all-props/) |
| pluginKey | `string | PluginKey` | `'floatingMenu'` | The key for the underlying ProseMirror plugin. |
| shouldShow | `(props) => boolean` | | Controls whether the menu should be shown or not. |
### element
The DOM element that contains your menu.
Type: `HTMLElement`
Default: `null`
### tippyOptions
Under the hood, the `BubbleMenu` uses [tippy.js](https://atomiks.github.io/tippyjs/v6/all-props/). You can directly pass options to it.
Type: `Object`
Default: `{}`
### pluginKey
The key for the underlying ProseMirror plugin. Make sure to use different keys if you add more than one instance.
Type: `string | PluginKey`
Default: `'floatingMenu'`
### shouldShow
A callback to control whether the menu should be shown or not.
Type: `(props) => boolean`
## Source code
[packages/extension-floating-menu/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-floating-menu/)

26
docs/api/extensions/focus.md
View File

@@ -16,10 +16,28 @@ yarn add @tiptap/extension-focus
```
## Settings
| Option | Type | Default | Description |
| --------- | -------- | ------------- | ---------------------------------------------------------------------------- |
| className | `String` | `'has-focus'` | The class that is applied to the focused element. |
| mode | `String` | `'all'` | Apply the class to `'all'`, the `'shallowest'` or the `'deepest'` node. |
### className
The class that is applied to the focused element.
Default: `'has-focus'`
```js
Focus.configure({
className: 'focus',
})
```
### mode
Apply the class to `'all'`, the `'shallowest'` or the `'deepest'` node.
Default: `'all'`
```js
Focus.configure({
mode: 'deepest',
})
```
## Source code
[packages/extension-focus/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-focus/)

31
docs/api/extensions/font-family.md
View File

@@ -16,14 +16,33 @@ yarn add @tiptap/extension-text-style @tiptap/extension-font-family
This extension requires the [`TextStyle`](/api/marks/text-style) mark.
## Settings
| Option | Type | Default | Description |
| ------ | ------- | --------------- | ------------------------------------------------------------------------ |
| types | `Array` | `['textStyle']` | A list of marks to which the font family attribute should be applied to. |
### types
A list of marks to which the font family attribute should be applied to.
Default: `['textStyle']`
```js
FontFamily.configure({
types: ['textStyle'],
})
```
## Commands
| Command | Parameters | Description |
| ---------- | ---------- | --------------------------------------------- |
| fontFamily | fontFamily | Applies the given font family as inline style |
### setFontFamily()
Applies the given font family as inline style.
```js
editor.commands.setFontFamily('Inter')
```
### unsetFontFamily()
Removes any font family.
```js
editor.commands.unsetFontFamily()
```
## Source code
[packages/extension-font-family/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-font-family/)

26
docs/api/extensions/history.md
View File

@@ -14,10 +14,28 @@ yarn add @tiptap/extension-history
```
## Settings
| Option | Type | Default | Description |
| ------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| depth | `Number` | `100` | The amount of history events that are collected before the oldest events are discarded. Defaults to 100. |
| newGroupDelay | `Number` | `500` | The delay between changes after which a new group should be started (in milliseconds). When changes aren’t adjacent, a new group is always started. |
### depth
The amount of history events that are collected before the oldest events are discarded. Defaults to 100.
Default: `100`
```js
History.configure({
depth: 10,
})
```
### newGroupDelay
The delay between changes after which a new group should be started (in milliseconds). When changes aren’t adjacent, a new group is always started.
Default: `500`
```js
History.configure({
newGroupDelay: 1000,
})
```
## Commands

77
docs/api/extensions/placeholder.md
View File

@@ -14,13 +14,76 @@ yarn add @tiptap/extension-placeholder
```
## Settings
| Option | Type | Default | Description |
| -------------------- | ------------------- | --------------------- | ----------------------------------------------------------- |
| emptyEditorClass | `String` | `'is-editor-empty'` | The added CSS class if the editor is empty. |
| emptyNodeClass | `String` | `'is-empty'` | The added CSS class if the node is empty. |
| placeholder | `String | Function` | `'Write something …'` | The placeholder text added as `data-placeholder` attribute. |
| showOnlyWhenEditable | `Boolean` | `true` | Show decorations only when editor is editable. |
| showOnlyCurrent | `Boolean` | `true` | Show decorations only in currently selected node. |
### emptyEditorClass
The added CSS class if the editor is empty.
Default: `'is-editor-empty'`
```js
Placeholder.configure({
emptyEditorClass: 'is-editor-empty',
})
```
### emptyNodeClass
The added CSS class if the node is empty.
Default: `'is-empty'`
```js
Placeholder.configure({
emptyNodeClass: 'my-custom-is-empty-class',
})
```
### placeholder
The placeholder text added as `data-placeholder` attribute.
Default: `'Write something …'`
```js
Placeholder.configure({
placeholder: 'My Custom Placeholder',
})
```
You can even use a function to add placeholder depending on the node:
```js
Placeholder.configure({
placeholder: ({ node }) => {
if (node.type.name === 'heading') {
return 'What’s the title?'
}
return 'Can you add some further context?'
},
})
```
### showOnlyWhenEditable
Show decorations only when editor is editable.
Default: `true`
```js
Placeholder.configure({
showOnlyWhenEditable: false,
})
```
### showOnlyCurrent
Show decorations only in currently selected node.
Default: `true`
```js
Placeholder.configure({
showOnlyCurrent: false
})
```
## Source code
[packages/extension-placeholder/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-placeholder/)

56
docs/api/extensions/text-align.md
View File

@@ -18,16 +18,56 @@ yarn add @tiptap/extension-text-align
```
## Settings
| Option | Type | Default | Description |
| ---------------- | -------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| types | `Array` | `[]` | A list of nodes where the text align attribute should be applied to. Usually something like `['heading', 'paragraph']`. |
| alignments | `Array` | `['left', 'center', 'right', 'justify']` | A list of available options for the text align attribute. |
| defaultAlignment | `String` | `'left'` | The default text align. |
### types
A list of nodes where the text align attribute should be applied to. Usually something like `['heading', 'paragraph']`.
Default: `[]`
```js
TextAlign.configure({
types: ['heading', 'paragraph'],
})
```
### alignments
A list of available options for the text align attribute.
Default: `['left', 'center', 'right', 'justify']`
```js
TextAlign.configure({
alignments: ['left', 'right'],
})
```
### defaultAlignment
The default text align.
Default: `'left'`
```js
TextAlign.configure({
defaultAlignment: 'right',
})
```
## Commands
| Command | Parameters | Description |
| --------- | ---------- | ------------------------------------------ |
| textAlign | alignment | Set the text align to the specified value. |
### setTextAlign()
Set the text align to the specified value.
```js
editor.commands.setTextAlign('right')
```
### unsetTextAlign()
Remove the text align value.
```js
editor.commands.unsetTextAlign()
```
## Keyboard shortcuts
| Command | Windows/Linux | macOS |