mirror/tiptap
1
0
Fork 0
mirror of https://github.com/ueberdosis/tiptap.git synced 2024-11-28 07:40:13 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: remove most of the tables from the content (to improve the searchability)

Browse Source
This commit is contained in:
Hans Pagel 2021-10-07 21:02:30 +02:00
parent 9ed883edd4
commit c5f025909e
8 changed files with 183 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
docs/api/commands.md
View File

@ -158,61 +158,61 @@ Have a look at all of the core commands listed below. They should give you a goo
### Content
| Command | Description | Links |
| ------------------ | -------------------------------------------------------- | --------------------------------------- |
| .clearContent() | Clear the whole document. | [More](/api/commands/clear-content) |
| .insertContent() | Insert a node or string of HTML at the current position. | [More](/api/commands/insert-content) |
| .insertContentAt() | Insert a node or string of HTML at a specific position. | [More](/api/commands/insert-content-at) |
| .setContent() | Replace the whole document with new content. | [More](/api/commands/set-content) |
| clearContent() | Clear the whole document. | [More](/api/commands/clear-content) |
| insertContent() | Insert a node or string of HTML at the current position. | [More](/api/commands/insert-content) |
| insertContentAt() | Insert a node or string of HTML at a specific position. | [More](/api/commands/insert-content-at) |
| setContent() | Replace the whole document with new content. | [More](/api/commands/set-content) |
### Nodes & Marks
| Command | Description | Links |
| ----------------------- | --------------------------------------------------------- | ------------------------------------ |
| .clearNodes() | Normalize nodes to a simple paragraph. | [More](/api/commands/clear-nodes) |
| .createParagraphNear() | Create a paragraph nearby. | [More](/api/commands/create-paragraph-near) |
| .deleteNode() | Delete a node. | [More](/api/commands/delete-node) |
| .extendMarkRange() | Extends the text selection to the current mark. | [More](/api/commands/extend-mark-range) |
| .exitCode() | Exit from a code block. | [More](/api/commands/exit-code) |
| .joinBackward() | Join two nodes backward. | [More](/api/commands/join-backward) |
| .joinForward() | Join two nodes forward. | [More](/api/commands/join-forward) |
| .lift() | Removes an existing wrap. | [More](/api/commands/lift) |
| .liftEmptyBlock() | Lift block if empty. | [More](/api/commands/lift-empty-block) |
| .newlineInCode() | Add a newline character in code. | [More](/api/commands/newline-in-code) |
| .resetAttributes() | Resets some node or mark attributes to the default value. | [More](/api/commands/reset-attributes) |
| .setMark() | Add a mark with new attributes. | [More](/api/commands/set-mark) |
| .setNode() | Replace a given range with a node. | [More](/api/commands/set-node) |
| .splitBlock() | Forks a new node from an existing node. | [More](/api/commands/split-block) |
| .toggleMark() | Toggle a mark on and off. | [More](/api/commands/toggle-mark) |
| .toggleNode() | Toggle a node with another node. | [More](/api/commands/toggle-node) |
| .toggleWrap() | Wraps nodes in another node, or removes an existing wrap. | [More](/api/commands/toggle-wrap) |
| .undoInputRule() | Undo an input rule. | [More](/api/commands/undo-input-rule) |
| .unsetAllMarks() | Remove all marks in the current selection. | [More](/api/commands/unset-all-marks) |
| .unsetMark() | Remove a mark in the current selection. | [More](/api/commands/unset-mark) |
| .updateAttributes() | Update attributes of a node or mark. | [More](/api/commands/update-attributes) |
| clearNodes() | Normalize nodes to a simple paragraph. | [More](/api/commands/clear-nodes) |
| createParagraphNear() | Create a paragraph nearby. | [More](/api/commands/create-paragraph-near) |
| deleteNode() | Delete a node. | [More](/api/commands/delete-node) |
| extendMarkRange() | Extends the text selection to the current mark. | [More](/api/commands/extend-mark-range) |
| exitCode() | Exit from a code block. | [More](/api/commands/exit-code) |
| joinBackward() | Join two nodes backward. | [More](/api/commands/join-backward) |
| joinForward() | Join two nodes forward. | [More](/api/commands/join-forward) |
| lift() | Removes an existing wrap. | [More](/api/commands/lift) |
| liftEmptyBlock() | Lift block if empty. | [More](/api/commands/lift-empty-block) |
| newlineInCode() | Add a newline character in code. | [More](/api/commands/newline-in-code) |
| resetAttributes() | Resets some node or mark attributes to the default value. | [More](/api/commands/reset-attributes) |
| setMark() | Add a mark with new attributes. | [More](/api/commands/set-mark) |
| setNode() | Replace a given range with a node. | [More](/api/commands/set-node) |
| splitBlock() | Forks a new node from an existing node. | [More](/api/commands/split-block) |
| toggleMark() | Toggle a mark on and off. | [More](/api/commands/toggle-mark) |
| toggleNode() | Toggle a node with another node. | [More](/api/commands/toggle-node) |
| toggleWrap() | Wraps nodes in another node, or removes an existing wrap. | [More](/api/commands/toggle-wrap) |
| undoInputRule() | Undo an input rule. | [More](/api/commands/undo-input-rule) |
| unsetAllMarks() | Remove all marks in the current selection. | [More](/api/commands/unset-all-marks) |
| unsetMark() | Remove a mark in the current selection. | [More](/api/commands/unset-mark) |
| updateAttributes() | Update attributes of a node or mark. | [More](/api/commands/update-attributes) |
### Lists
| Command | Description | Links |
| ---------------- | ------------------------------------------- | ------------------------------------ |
| .liftListItem() | Lift the list item into a wrapping list. | [More](/api/commands/lift-list-item) |
| .sinkListItem() | Sink the list item down into an inner list. | [More](/api/commands/sink-list-item) |
| .splitListItem() | Splits one list item into two list items. | [More](/api/commands/split-list-item) |
| .toggleList() | Toggle between different list types. | [More](/api/commands/toggle-list) |
| .wrapInList() | Wrap a node in a list. | [More](/api/commands/wrap-in-list) |
| liftListItem() | Lift the list item into a wrapping list. | [More](/api/commands/lift-list-item) |
| sinkListItem() | Sink the list item down into an inner list. | [More](/api/commands/sink-list-item) |
| splitListItem() | Splits one list item into two list items. | [More](/api/commands/split-list-item) |
| toggleList() | Toggle between different list types. | [More](/api/commands/toggle-list) |
| wrapInList() | Wrap a node in a list. | [More](/api/commands/wrap-in-list) |
### Selection
| Command | Description | Links |
| --------------------- | --------------------------------------- | ------------------------------------ |
| .blur() | Removes focus from the editor. | [More](/api/commands/blur) |
| .deleteRange() | Delete a given range. | [More](/api/commands/delete-range) |
| .deleteSelection() | Delete the selection, if there is one. | [More](/api/commands/delete-selection) |
| .enter() | Trigger enter. | [More](/api/commands/enter) |
| .focus() | Focus the editor at the given position. | [More](/api/commands/focus) |
| .keyboardShortcut() | Trigger a keyboard shortcut. | [More](/api/commands/keyboard-shortcut) |
| .scrollIntoView() | Scroll the selection into view. | [More](/api/commands/scroll-into-view) |
| .selectAll() | Select the whole document. | [More](/api/commands/select-all) |
| .selectNodeBackward() | Select a node backward. | [More](/api/commands/select-node-backward) |
| .selectNodeForward() | Select a node forward. | [More](/api/commands/select-node-forward) |
| .selectParentNode() | Select the parent node. | [More](/api/commands/select-parent-node) |
| .setNodeSelection() | Creates a NodeSelection. | [More](/api/commands/set-node-selection) |
| .setTextSelection() | Creates a TextSelection. | [More](/api/commands/set-text-selection) |
| blur() | Removes focus from the editor. | [More](/api/commands/blur) |
| deleteRange() | Delete a given range. | [More](/api/commands/delete-range) |
| deleteSelection() | Delete the selection, if there is one. | [More](/api/commands/delete-selection) |
| enter() | Trigger enter. | [More](/api/commands/enter) |
| focus() | Focus the editor at the given position. | [More](/api/commands/focus) |
| keyboardShortcut() | Trigger a keyboard shortcut. | [More](/api/commands/keyboard-shortcut) |
| scrollIntoView() | Scroll the selection into view. | [More](/api/commands/scroll-into-view) |
| selectAll() | Select the whole document. | [More](/api/commands/select-all) |
| selectNodeBackward() | Select a node backward. | [More](/api/commands/select-node-backward) |
| selectNodeForward() | Select a node forward. | [More](/api/commands/select-node-forward) |
| selectParentNode() | Select the parent node. | [More](/api/commands/select-parent-node) |
| setNodeSelection() | Creates a NodeSelection. | [More](/api/commands/set-node-selection) |
| setTextSelection() | Creates a TextSelection. | [More](/api/commands/set-text-selection) |
<!-- ## Example use cases

34
docs/api/events.md
View File

@ -9,16 +9,30 @@ The editor fires a few different events that you can hook into. Let’s have a l
## List of available events
| Event | Description |
| --------------- | --------------------------------- |
| beforeCreate | Before the view is created. |
| create | The editor is ready. |
| update | The content has changed. |
| selectionUpdate | The selection has changed. |
| transaction | The editor state has changed. |
| focus | The editor is focused. |
| blur | The editor isn’t focused anymore. |
| destroy | The editor is being destroyed. |
### beforeCreate
Before the view is created.
### create
The editor is ready.
### update
The content has changed.
### selectionUpdate
The selection has changed.
### transaction
The editor state has changed.
### focus
The editor is focused.
### blur
The editor isn’t focused anymore.
### destroy
The editor is being destroyed.
## Register event listeners
There are three ways to register event listeners.

8
docs/api/extensions/unique-id.md
View File

@ -1,8 +0,0 @@
# UniqueId
The `UniqueId` extension adds unique IDs to all nodes. The extension keeps track of your nodes, even if you split them, merge them, undo/redo changes, crop content, paste content … It just works.
Also, you can configure which node types get an unique ID, and which not, and you can customize how those IDs are generated.
:::pro Pro extension
The UniqueId extension is the first tiptap pro extension we have released on top of all the free extensions. Access to the extension and the documentation requires a tiptap pro subscription. [Become a tiptap pro now!](/pricing)
:::

57
docs/api/utilities/suggestion.md
View File

@ -5,17 +5,52 @@
This utility helps with all kinds of suggestions in the editor. Have a look at the [`Mention`](/api/nodes/mention), [`Hashtag`](/api/nodes/hashtag) or [`Emoji`](/api/nodes/emoji) node to see it in action.
## Settings
| Option | Type | Default | Description |
| --------------- | ----------- | --------------------- | ----------------------------------------------------------- |
| char | `String` | `'@'` | The character that triggers the autocomplete popup. |
| pluginKey | `PluginKey` | `SuggestionPluginKey` | A ProseMirror PluginKey. |
| allowSpaces | `Boolean` | `false` | Allows or disallows spaces in suggested items. |
| startOfLine | `Boolean` | `false` | Trigger the autocomplete popup at the start of a line only. |
| decorationTag | `String` | `'span'` | The HTML tag that should be rendered for the suggestion. |
| decorationClass | `String` | `'suggestion'` | A CSS class that should be added to the suggestion. |
| command | `Function` | `() => {}'` | Executed when a suggestion is selected. |
| items | `Function` | `() => {}` | Pass an array of filtered suggestions, can be async. |
| render | `Function` | `() => ({})` | A render function for the autocomplete popup. |
### char
The character that triggers the autocomplete popup.
Default: `'@'`
### pluginKey
A ProseMirror PluginKey.
Default: `SuggestionPluginKey`
### allowSpaces
Allows or disallows spaces in suggested items.
Default: `false`
### startOfLine
Trigger the autocomplete popup at the start of a line only.
Default: `false`
### decorationTag
The HTML tag that should be rendered for the suggestion.
Default: `'span'`
### decorationClass
A CSS class that should be added to the suggestion.
Default: `'suggestion'`
### command
Executed when a suggestion is selected.
Default: `() => {}'`
### items
Pass an array of filtered suggestions, can be async.
Default: `() => {}`
### render
A render function for the autocomplete popup.
Default: `() => ({})`
## Source code
[packages/suggestion/](https://github.com/ueberdosis/tiptap/blob/main/packages/suggestion/)

33
docs/guide/node-views/react.md
View File

@ -99,16 +99,29 @@ The `NodeViewWrapper` and `NodeViewContent` components render a `<div>` HTML tag
## All available props
Here is the full list of what props you can expect:
| Prop | Description |
| ------------------ | --------------------------------------------------------------- |
| `editor` | The editor instance |
| `node` | The current node |
| `decorations` | An array of decorations |
| `selected` | `true` when there is a `NodeSelection` at the current node view |
| `extension` | Access to the node extension, for example to get options |
| `getPos` | Get the document position of the current node |
| `updateAttributes` | Update attributes of the current node |
| `deleteNode` | Delete the current node |
### editor
The editor instance
### node
The current node
### decorations
An array of decorations
### selected
`true` when there is a `NodeSelection` at the current node view
### extension
Access to the node extension, for example to get options
### getPos()
Get the document position of the current node
### updateAttributes()
Update attributes of the current node
### deleteNode()
Delete the current node
## Dragging
To make your node views draggable, set `draggable: true` in the extension and add `data-drag-handle` to the DOM element that should function as the drag handle.

30
docs/guide/node-views/vue.md
View File

@ -119,7 +119,33 @@ Keep in mind that this content is rendered by tiptap. That means you need to tel
The `NodeViewWrapper` and `NodeViewContent` components render a `<div>` HTML tag (`<span>` for inline nodes), but you can change that. For example `<node-view-content as="p">` should render a paragraph. One limitation though: That tag must not change during runtime.
## All available props
For advanced use cases, we pass a few more props to the component. Here is the full list of what props you can expect:
For advanced use cases, we pass a few more props to the component.
### editor
The editor instance.
### node
Access the current node.
### decorations
An array of decorations.
### selected
`true` when there is a `NodeSelection` at the current node view.
### extension
Access to the node extension, for example to get options.
### getPos()
Get the document position of the current node.
### updateAttributes()
Update attributes of the current node.
### deleteNode()
Delete the current node.
Here is the full list of what props you can expect:
```html
<template>
@ -179,7 +205,7 @@ export default {
</script>
```
If you just want to have all (and to have TypeScript support) you can import all props like that:
If you just want to have all (and TypeScript support) you can import all props like that:
```js
// Vue 3

35
docs/overview/upgrade-guide.md
View File

@ -4,7 +4,7 @@ tableOfContents: true
# Upgrade Guide
## Reasons to upgrade to tiptap v2
## Introduction
First of all, tiptap v1 isn’t supported anymore and won’t receive any further updates.
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.
@ -15,10 +15,9 @@ Yes, it’s tedious work to upgrade your favorite text editor to a new API, but
* Tons of new extensions
* Well-tested code base
## Upgrading from v1 to v2
The new API will look pretty familiar to you, but there are a ton of changes though. To make the upgrade a little bit easier, here is everything you need to know:
### Uninstall tiptap v1
## Uninstall tiptap v1
The whole package structure has changed, we even moved to another npm namespace, so you’ll need to remove the old version entirely before upgrading to tiptap 2.
Otherwise you’ll run into an exception, for example “looks like multiple versions of prosemirror-model were loaded”.
@ -31,7 +30,7 @@ npm uninstall tiptap tiptap-commands tiptap-extensions tiptap-utils
yarn remove tiptap tiptap-commands tiptap-extensions tiptap-utils
```
### Install tiptap v2
## Install tiptap v2
Once you have uninstalled the old version of tiptap, install the new Vue 2 package and the starter kit:
@ -43,7 +42,7 @@ npm install @tiptap/vue-2 @tiptap/starter-kit
yarn add @tiptap/vue-2 @tiptap/starter-kit
```
### Keep tiptap v2 up to date
## Keep tiptap v2 up to date
We are constantly releasing updates to tiptap. Did you know there’s an easy-to-use command to update your dependencies with Yarn?
```bash
@ -56,7 +55,7 @@ You can add the `--latest` flag, to show all possible upgrades – even if they
yarn upgrade-interactive --latest
```
### Explicitly register the Document, Text and Paragraph extensions
## 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/nodes/document), [`Paragraph`](/api/nodes/paragraph) and [`Text`](/api/nodes/text) extensions.
```js
@ -76,7 +75,7 @@ new Editor({
And we removed some settings: `dropCursor`, `enableDropCursor`, and `enableGapCursor`. Those are separate extensions now: [`Dropcursor`](/api/extensions/dropcursor) and [`Gapcursor`](/api/extensions/gapcursor). You probably want to load them, but if you don’t, just ignore this.
### New names for most extensions
## New names for most extensions
We switched to lowerCamelCase, so there’s a lot type names that changed. If you stored your content as JSON you need to loop through it and rename them. Sorry for that one.
| Old type | New type |
@ -93,10 +92,10 @@ We switched to lowerCamelCase, so there’s a lot type names that changed. If yo
| ~~`todo_list`~~ | `taskList` (new name!) |
| ~~`todo_item`~~ | `taskItem` (new name!) |
### Removed methods
## Removed methods
We removed the `.state()` method. No worries though, it’s still available through `editor.state`.
### New extension API
## New extension API
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
@ -131,14 +130,14 @@ const CustomExtension = Node.create({
Read more about [all the nifty details building custom extensions](/guide/custom-extensions) in our guide.
### Renamed settings and methods
## Renamed settings and methods
[We renamed a lot of settings and methods](/api/editor). Hopefully you can migrate to the new API with search & replace. Here is a list of what changed:
| Old name | New name |
| --------------- | ----------- |
| ~~`autoFocus`~~ | `autofocus` |
### Renamed commands
## Renamed commands
All new extensions come with specific commands to set, unset and toggle styles. So instead of `.bold()`, it’s now `.toggleBold()`. Also, we switched to lowerCamelCase, below are a few examples. Oh, and we renamed `todo_list`, to `taskList`, sorry for that one.
| Old command | New command |
@ -162,10 +161,10 @@ All new extensions come with specific commands to set, unset and toggle styles.
| ~~`.underline()`~~ | `.toggleUnderline()` |
| … | … |
### MenuBar, BubbleMenu and FloatingMenu
## MenuBar, BubbleMenu and FloatingMenu
Read the dedicated [guide on creating menus](/guide/menus) to migrate your menus.
### Commands can be chained now
## Commands can be chained now
Most commands can be combined to one call now. That’s shorter than separate function calls in most cases. Here is an example to make the selected text bold:
```js
@ -174,7 +173,7 @@ editor.chain().toggleBold().focus().run()
The `.chain()` is required to start a new chain and the `.run()` is needed to actually execute all the commands in between. Read more about [the new tiptap commands](/api/commands) in our API documentation.
### .focus() isn’t called on every command anymore
## .focus() isn’t called on every command anymore
We tried to hide the `.focus()` command from you with tiptap 1 and executed that on every command. That led to issues in specific use cases, where you want to run a command, but don’t want to focus the editor.
With tiptap v2 you have to explicitly call the `focus()` and you probably want to do that in a lot of places. Here is an example:
@ -183,18 +182,18 @@ With tiptap v2 you have to explicitly call the `focus()` and you probably want t
editor.chain().focus().toggleBold().run()
```
### Event callbacks have fewer parameters
## Event callbacks have fewer parameters
The new event callbacks have fewer parameters. The same things should be available through `this.` now. [Read more about events here.](/api/events)
### Collaborative editing
## Collaborative editing
The reference implementation for collaborative editing uses Y.js now. That’s a whole different thing. You still can use the tiptap 1 extension, but it’s up to you to adapt it to the new extension API. If you’ve done this, don’t forget to share it with us so we can link to it from here!
Read more about [the new collaborative editing experience](/guide/collaborative-editing) in our guide.
### Marks don’t support node view anymore
## Marks don’t support node view anymore
For marks, node views are [not well supported in ProseMirror](https://discuss.prosemirror.net/t/there-is-a-bug-in-marks-nodeview/2722/2). There is also [a related issue](https://github.com/ueberdosis/tiptap/issues/613) for tiptap 1. That’s why we removed it in tiptap 2.
### Become a sponsor
## Become a sponsor
tiptap wouldn’t exist without the funding of its community. If you fell in love with tiptap, don’t forget to [become a sponsor](/sponsor) and make the maintenance, development and support sustainable.
In exchange, we’ll take you into our hearts, invite you to private repositories, add a `sponsor ♥` label to your issues and pull requests and more.

4
docs/sponsor.md
View File

@ -43,7 +43,7 @@ If you’re a company, don’t want to use GitHub, don’t have a credit card or
We are part of the [Y-Collective](https://opencollective.com/y-collective), a fund for projects related to Y.js (the technology we’re using for all the collaborative editing magic). That’s an OpenCollective, which allows you to send money through transfer, PayPal or credit card. Donations are tax deductible for US companies.
### I want consulting. What’s your rate?
We don’t do any calls, consulting or personal support for tiptap. If you have an issue, a question, want to talk something through or anything else, [please use GitHub issues](https://github.com/ueberdosis/tiptap/issues) to keep everything accessible for the whole community.
If you have an issue, a question, want to talk something through or anything else, [please use GitHub issues](https://github.com/ueberdosis/tiptap/issues/new/choose) to keep everything accessible to the whole community. For everything else, reach out to [humans@tiptap.dev](mailto:humans@tiptap.dev). We can take on a limited number of custom development and consulting contracts.
### Can we have a call?
Nope, we are big fans of asynchronous communication. If you really need to reach out in private, send us an email to [humans@tiptap.dev](mailto:humans@tiptap.dev), but don’t expect technical email support.
Nope, we are big fans of asynchronous communication. If you really need to reach out in private, send us an email to [humans@tiptap.dev](mailto:humans@tiptap.dev), but don’t expect technical email support. That all happens on [GitHub](https://github.com/ueberdosis/tiptap/issues).